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

> Explore how Archify viewer's route tracing works. Visualize shortest paths interactively on SVG diagrams using the Archify routeProbe module. Learn more now.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html).

### The PATH Toolbar Button

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

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

```

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`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) at lines 4928-4947:

```html
<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:

```css
.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:

```javascript
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:

```javascript
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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.