How Route Tracing Works in the Archify Viewer: A Complete Technical Guide

The Archify viewer's route tracing feature lets users interactively select a source and destination node on any SVG diagram, visualizes the shortest path with an animated flow overlay, and generates shareable URLs—all through the Archify.routeProbe module accessible via keyboard shortcut R or the PATH toolbar button.

Route tracing in Archify is a self-contained, attribute-driven system that works across any diagram following the viewer's SVG conventions. This guide walks through the implementation details, public API, and practical usage examples drawn directly from the source code in tt-a1i/archify.

---

Activating Route Tracing: UI Entry Points

Users can initiate route tracing through two interfaces defined in archify/assets/template.html.

The PATH Toolbar Button

The toolbar button sits at lines 11321-11330 and toggles the route-probe panel:

<button id="btn-route-probe" type="button"
        aria-label="Trace a directed route"
        aria-pressed="false"
        aria-controls="route-probe"
        title="Trace route (R)">PATH</button>

Clicking this button or pressing R invokes Archify.routeProbe.toggle({focusNode:true}) at line 13223.

Keyboard Shortcut Handling

The viewer binds the R key globally. When pressed, it calls the same toggle() method, making route tracing accessible without mouse interaction.

---

The Route-Probe Panel Structure

The side panel is defined in experiments/mco-showcase/mco-runtime.html at lines 4928-4947:

<div class="route-probe no-print" id="route-probe" hidden role="region"
     aria-labelledby="route-probe-title" data-state="idle">
  <!-- Dynamic title: "Choose a start node" → "Choose a destination" → "Route" -->
  <h3 id="route-probe-title">Choose a start node</h3>
  
  <!-- Action buttons -->
  <button id="route-probe-find">Find start</button>
  <button id="route-probe-copy">Copy link</button>
  <button id="route-probe-clear">Clear</button>
  
  <!-- Instructional placeholder -->
  <p class="route-probe-hint">Pick two semantic nodes on the diagram</p>
</div>

The panel's data-state attribute tracks progress through the selection flow: idle → source → target → complete.

---

The RouteProbe Module Architecture

Archify.routeProbe is implemented as an immediately-invoked function expression (IIFE) starting at line 11317. This encapsulates private state while exposing a stable public API.

Core Public Methods

Method	Purpose	Source Location
toggle(opts)	Opens/closes panel and manages node-click listeners	Line 13223
begin({focusNode, source, target})	Starts a new trace with optional pre-selected nodes	Line 13086
choose(nodeId)	Records start or end node; auto-computes path when both selected	Referenced at line 11166
clear({updateUrl, restoreFocus})	Removes overlays and resets UI state	Lines 8090-8091
active()	Returns 'source', 'target', or false indicating current step	Line 8398
exportSnapshot()	Serializes route for sharing and WebM export	Line 6010
escape({restoreFocus})	Cancels probe on Esc key	Lines 13248-13250

State Management Hooks

The module integrates with the Find UI through finderOpening() and finderClosed() (lines 11238-11239) and handles page visibility via pauseJourney() and syncMotion() (lines 6765-6769).

---

How Route Rendering Works

Once both nodes are selected, choose() triggers path computation and visual overlay injection.

DOM Attribute Marking

The module manipulates data attributes directly on SVG elements:

• Start node receives data-route-start
• End node receives data-route-end
• Edges along the path receive data-route-match

Flow Animation Implementation

A cloned path segment animates to show direction. The CSS driving this lives in the same template at lines 4043 and 4306:

.route-probe-flow {
    animation: archify-route-probe-flow 1.1s cubic-bezier(0.22, 1, 0.36, 1) 1 both;
}

The easing function (0.22, 1, 0.36, 1) creates a smooth deceleration effect as the flow reaches the destination.

---

Complete Interaction Flow

1. Activation — toggle() adds data-route-probe-overlay to the SVG container and reveals the panel
2. Source selection — Clicking any node with data-node-id calls choose(id), marks data-route-start, and updates the panel title
3. Target selection — Second node click marks data-route-end, invokes Archify's internal graph utilities for shortest-path calculation, and injects route-probe-flow elements
4. Completion — Panel displays the full path and enables Copy link functionality
5. Cleanup — Clear button or Esc key calls clear() to remove all overlays

---

Programmatic Usage Examples

Start a Route from Code

Pre-select nodes without user interaction—useful for automated demos or deep-linking:

Archify.routeProbe.begin({
    source: "node-123",   // pre-select start node
    target: "node-456",   // pre-select destination
    focusNode: false      // keep panel minimized if desired
});

This pattern appears in the test suite at archify/test/webm-artifact.smoke.mjs line 968.

Generate a Shareable URL

Capture the current trace for sharing:

if (Archify.routeProbe.active()) {
    const snapshot = Archify.routeProbe.exportSnapshot();
    const shareUrl = `${location.origin}${location.pathname}?route=${snapshot.id}`;
    navigator.clipboard.writeText(shareUrl);
}

The exportSnapshot() method at line 6010 returns an object containing the serialized route identifier.

Clean Up Programmatically

Reset state without URL updates:

Archify.routeProbe.clear({updateUrl: false, restoreFocus: true});

The restoreFocus: true parameter returns keyboard focus to the triggering element for accessibility.

---

Key Source Files and Locations

File	Purpose
experiments/mco-showcase/mco-runtime.html	Panel markup (lines 4928-4947), module IIFE (line 11317), toggle (line 13223), begin (line 13086)
archify/assets/template.html	Toolbar button (lines 11321-11330), CSS animations (lines 4043, 4306)
archify/test/webm-artifact.smoke.mjs	Programmatic begin() usage in tests (line 968)
examples/web-app.html	Toolbar integration example

---

Summary

• Route tracing is activated via R key or PATH button, calling Archify.routeProbe.toggle()
• State machine tracks progress through active() returning 'source', 'target', or false
• Visual feedback uses data attributes (data-route-start, data-route-end, data-route-match) and CSS animations
• Public API enables programmatic control through begin(), choose(), clear(), and exportSnapshot()
• Universal compatibility works on any diagram with standard Archify SVG conventions

---

Frequently Asked Questions

How do I disable the route tracing feature in my Archify deployment?

Remove or hide the #btn-route-probe button element and omit the keyboard binding for R. The Archify.routeProbe module initializes lazily, so if toggle() is never called, no listeners attach and no overhead is incurred.

Can I programmatically set both nodes without showing the panel?

Yes. Pass focusNode: false to begin() as shown in the test suite at line 968. This computes and renders the route immediately while keeping the UI collapsed.

What algorithm computes the shortest path?

The source uses Archify's internal graph utilities through the choose() method's implementation. The exact algorithm is not exposed in the public API, but it operates on the data-edge-from and data-edge-to attributes present in the SVG.

Why does my custom diagram not show route traces?

Ensure your SVG elements include data-node-id on nodes and data-edge-from/data-edge-to on edges. The route probe queries these attributes exclusively; it does not parse visual geometry or path data.

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