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

Route tracing in Archify works through a self-contained Archify.routeProbe module that lets users interactively select source and destination nodes, visualizes the shortest path with animated flow overlays, and exports shareable snapshots.

The Archify viewer ships with a built-in route tracing system for exploring directed connections between semantic nodes. This feature is implemented entirely in the frontend as an attribute-driven overlay system that requires no server round-trips. Below is the complete technical architecture of how it operates.

---

UI Entry Points: Keyboard and Toolbar Activation

Users can activate route tracing through two interfaces.

The PATH Toolbar Button

The button is defined in archify/assets/template.html:

<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>

This markup appears at line 11321-11330.

The Keyboard Shortcut

Pressing R triggers the same toggle handler. Both inputs call:

Archify.routeProbe.toggle({focusNode: true})

The implementation is located at line 13223.

---

The Route-Probe Panel Structure

When activated, a side panel slides into view. The markup resides 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>
  <!-- Controls: Find start, Copy link, Clear -->
  <!-- Placeholder: "Pick two semantic nodes on the diagram" -->
</div>

The panel's data-state attribute cycles through idle, source, target, and complete to drive UI transitions.

---

The RouteProbe State Machine

The module is instantiated as an IIFE at line 11317:

Archify.routeProbe = (function () {
    // Private state
    let _source = null;
    let _target = null;
    let _active = false;
    
    // Public API returned
    return { /* methods */ };
})();

Core Public Methods

Method	Purpose	Source Location
begin({focusNode, source, target})	Initiates trace with optional pre-selected nodes	line 13086
toggle(opts)	Opens/closes panel and attaches/detaches click listeners	line 13223
choose(nodeId)	Records selections; computes path when both nodes chosen	referenced at line 11166
clear({updateUrl, restoreFocus})	Removes overlays and resets state	lines 8090-8091
active()	Returns 'source'| 'target' | false for current step	line 8398
exportSnapshot()	Serializes route for sharing/WebM export	line 6010
escape({restoreFocus})	Cancels on Esc key	lines 13248-13250

---

Visualizing the Route with SVG Overlays

Once both nodes are selected, the module injects visual indicators directly into the SVG DOM:

1. Start node receives data-route-start="true"
2. End node receives data-route-end="true"
3. Connecting edges receive data-route-match="true"
4. Flow animation is applied via a cloned path element with class route-probe-flow

The CSS animation driving this visualization:

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

Find the keyframes at line 4306 and class definition at line 4043.

---

Complete Interaction Flow (Step-by-Step)

1. Activation — toggle() adds data-route-probe-overlay to the SVG container and reveals the panel

2. Source selection — User clicks a node; choose(id) marks it and updates panel title to "Choose a destination"

3. Target selection — Second click triggers path computation using Archify's internal graph utilities, then injects overlay elements

4. Completion — Panel displays route summary and enables Copy link button powered by exportSnapshot()

5. Termination — User clicks Clear, presses Esc (triggering escape()), or toggles the feature off

---

Programmatic Route Tracing API

Pre-select a Route from Code

// From archify/test/webm-artifact.smoke.mjs at line 968
Archify.routeProbe.begin({
    source: "node-123",   // optional: pre-select start
    target: "node-456",   // optional: pre-select end
    focusNode: false      // keep panel minimized if desired
});

Generate a Shareable URL

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

This pattern appears at line 6010.

Clean Removal of Traces

Archify.routeProbe.clear({
    updateUrl: false,      // don't modify browser history
    restoreFocus: true     // return focus to triggering element
});

See implementation at lines 8090-8091.

---

Cross-Diagram Compatibility

The route tracing feature works on any diagram following Archify's SVG conventions:

• Nodes must expose data-node-id attributes
• Edges must expose data-edge-from and data-edge-to attributes

The routeProbe module operates purely on DOM traversal and data attributes—it has no dependency on specific diagram types or backend schemas.

---

Key Source Files Reference

File	Contains
archify/assets/template.html	Core Archify.routeProbe IIFE and toolbar button
experiments/mco-showcase/mco-runtime.html	Panel markup, CSS animations, method implementations
examples/web-app.html	Toolbar integration examples
archify/test/webm-artifact.smoke.mjs	Programmatic API usage in tests
examples/checkout-platform-delta.html	Full UI workflow demonstrations

---

Summary

• Route tracing is encapsulated in the Archify.routeProbe object, created as an IIFE in the main template
• User activation happens via the R key or PATH button, both calling toggle({focusNode: true})
• State management tracks selection progress through active() returning 'source', 'target', or false
• Visual rendering applies data-route-* attributes and CSS-animated flow overlays to SVG elements
• Export functionality serializes routes via exportSnapshot() for URL sharing and WebM artifact generation
• Programmatic control allows pre-selected routes through begin({source, target}) and cleanup via clear()

---

Frequently Asked Questions

How do I enable route tracing programmatically without user interaction?

Call Archify.routeProbe.begin({source: "node-id", target: "node-id"}) with optional node IDs. Set focusNode: false to suppress UI focus if you need background operation. This pattern is demonstrated in the test suite at line 968.

What happens when I press Escape during route selection?

The escape({restoreFocus: true}) method cancels the current trace, removes all overlay attributes from the SVG, resets the panel to data-state="idle", and returns focus to the element that activated the probe. Implementation at lines 13248-13250.

Can route tracing work on custom diagram types?

Yes. The module only requires standard Archify SVG conventions: data-node-id on nodes and data-edge-from/data-edge-to on edges. It performs DOM-based pathfinding without server dependencies, making it compatible with any diagram using these attributes.

How is the animated flow effect implemented?

The animation uses a CSS keyframe sequence applied to a cloned path element with class route-probe-flow. The timing function cubic-bezier(0.22, 1, 0.36, 1) creates an ease-out-quint curve for smooth deceleration. See the CSS at line 4043 and keyframes at line 4306.

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