# Archify Viewer Focus, Reach, Route, and Lens Features Explained

> Explore Archify viewer features: Focus, Reachability, Route Probing, and Semantic Lens. Inspect nodes, trace dependencies, animate paths, and browse relationships in self-contained HTML.

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

---

**The Archify interactive diagram viewer ships with four core capabilities—Focus for node inspection, Reachability for dependency tracing, Route Probing for path animation, and the Semantic Lens for relationship browsing—that operate entirely within self-contained HTML output using zero external dependencies.**

The tt-a1i/archify repository generates deterministic architecture diagrams through `archify/bin/archify.mjs`, producing a portable HTML file with a built-in JavaScript viewer layer. These **Archify viewer focus reach route lens features** enable developers to explore complex system graphs via direct SVG manipulation, implementing sophisticated traversal algorithms without requiring runtime libraries or build steps.

## Viewer Architecture and Zero-Dependency Design

The viewer consists of lightweight JavaScript modules that attach to a single `<svg>` element inside `.diagram-container`. Each module follows an isolation pattern demonstrated in [`viewer/focus.js`](https://github.com/tt-a1i/archify/blob/main/viewer/focus.js) and [`viewer/route-probe.js`](https://github.com/tt-a1i/archify/blob/main/viewer/route-probe.js), where private state and helper functions are encapsulated within immediately-invoked function expressions.

Key architectural constraints include:

- **State isolation**: Modules maintain private variables (`mode`, `activeIds`, `activeEdges`) and expose minimal public APIs through the `Archify` namespace.
- **Declarative DOM hooks**: UI elements (`#focus-chip`, `#route-probe`, `#relationship-lens-list`) are identified at load time and updated via data attributes (`data-reach-match`, `data-route-active`, `data-reach-depth`).
- **Zero runtime dependencies**: All behavior uses native DOM APIs, ensuring exported files remain self-contained per the contract defined in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).

## Focus and Reachability Analysis

The **Focus** feature centers on the `set(activeId)` function in [`viewer/focus.js`](https://github.com/tt-a1i/archify/blob/main/viewer/focus.js), which triggers `renderPassport` to populate the node inspection pane with metadata and controls.

### Node Focusing and Passport Rendering

When a user selects a node, the viewer calls `Archify.focus.set(nodeId)` to activate focus mode. This function retrieves the node's semantic data, updates the passport pane (`#focus-chip`), and prepares the canvas for reachability calculations. The passport displays the node's label, type, and immediate statistics while providing buttons to trigger upstream or downstream analysis.

### Upstream and Downstream Reachability

Reachability computation determines all nodes accessible from the focused node through directed edges:

1. **Edge extraction**: `reachabilityRelationships()` scans the SVG DOM for `data-edge-from` and `data-edge-to` attributes, building an adjacency list of connections.
2. **BFS traversal**: `computeReachability(originId, direction, relationships)` executes a breadth-first search, recording traversal depth per node and collecting the set of edge keys belonging to the reachable sub-graph.
3. **Visual application**: `applyReachability(direction, options)` marks matching nodes with `data-reach-depth` attributes and updates UI counters on `#btn-reach-upstream` and `#btn-reach-downstream`.

The status bar `#focus-reach-status` displays aggregate statistics after each computation cycle.

## Semantic Lens Relationship Navigation

While a node remains focused, the **Semantic Lens** displays its complete set of relationships grouped by direction. This feature is implemented through three primary functions in [`viewer/focus.js`](https://github.com/tt-a1i/archify/blob/main/viewer/focus.js):

- **`relationshipsFor(id, byId)`**: Iterates over all edges to build relationship objects containing directionality (`in`, `out`, `loop`), neighbor labels, and localized descriptions.
- **`renderRelationshipLens(id, byId)`**: Groups relationships by direction and injects formatted HTML into `#relationship-lens-list`, creating an expandable inspection interface.
- **`installRelationshipHitTargets()`**: Generates invisible overlay elements (`relationship-hit-overlay`) with `relationship-hit-target` classes for each edge, enabling keyboard navigation and screen reader accessibility via `aria-label` attributes.

Clicking a relationship hit target invokes `inspectRelationship(key)`, which highlights the specific edge, updates the passport summary, and triggers `Archify.view.reveal` to center both connected nodes within the viewport.

## Route Probing and Path Animation

The **Route Probe** module in [`viewer/route-probe.js`](https://github.com/tt-a1i/archify/blob/main/viewer/route-probe.js) enables users to visualize the shortest directed path between two nodes through a two-stage selection workflow.

### BFS Pathfinding Implementation

The workflow begins with `begin()`, which activates source selection mode and highlights valid start nodes. After the user selects an origin via `chooseStart(sourceId)`, the system marks reachable candidates with `data-route-candidate` attributes. Upon destination selection, `choose(targetId)` invokes `shortestDirectedPath(source, target)`, which performs BFS over the adjacency structure generated by `outgoingByNode()`.

### Journey Animation Controls

Once a path is calculated, the viewer renders animated flow indicators:

- **`renderOverlay()`**: Clones edge geometries to create translucent flow lines with the `route-probe-flow` class.
- **Motion governance**: Animation sequences coordinate through `Archify.motionGovernor`, which manages motion tokens to prevent performance degradation. Functions `playJourney()` and `scheduleJourney()` drive `animateMotion` elements along the calculated path.
- **Navigation UI**: The path panel (`#route-probe-path`) displays clickable hop buttons (`data-route-journey-index`) managed by `applyJourneyState()`, allowing step-by-step or automated playback.

The module supports deep linking via URL hash fragments (`#route=startId~endId`), synchronized through `copyLink()` and `syncFromHash()` functions.

## Programmatic Viewer Control

Developers can drive the viewer programmatically without UI interaction:

```javascript
// Assume Archify is already loaded on the page
const nodeId = 'database-1';       // a stable data-node-id from the diagram
Archify.focus.set(nodeId);         // open the passport pane
Archify.focus.applyReachability('upstream'); // highlight all upstream nodes

```

```javascript
// Start the route‑probe UI
Archify.routeProbe.begin();          // puts the viewer in source mode

// Choose the start and end nodes (normally done via UI clicks)
Archify.routeProbe.chooseStart('frontend');
Archify.routeProbe.choose('backend'); // triggers shortestDirectedPath & animation

```

```javascript
// After focusing a node, the lens creates hit targets.
// Grab the first relationship key from the rendered list:
const firstKey = document.querySelector('[data-relationship-key]').dataset.relationshipKey;

// Pin the relationship (highlights it and updates the passport)
Archify.focus.inspectRelationship(firstKey);

// Copy a shareable link for the pinned relationship:
Archify.focus.copyBtn.click();   // triggers copy to clipboard

```

## Summary

- **Focus** functionality in [`viewer/focus.js`](https://github.com/tt-a1i/archify/blob/main/viewer/focus.js) provides node inspection through `set()` and `renderPassport()`, displaying semantic metadata in the passport pane.
- **Reachability** analysis uses `computeReachability()` with BFS traversal to calculate upstream and downstream dependencies, applying `data-reach-depth` attributes for visual highlighting.
- The **Semantic Lens** renders relationship lists via `renderRelationshipLens()` and creates accessible interaction targets through `installRelationshipHitTargets()`.
- **Route Probing** in [`viewer/route-probe.js`](https://github.com/tt-a1i/archify/blob/main/viewer/route-probe.js) implements `shortestDirectedPath()` using BFS graph search, with animations governed by the motion governor system.
- All features manipulate the SVG DOM directly through data attributes, maintaining zero external dependencies and ensuring complete portability of generated architecture diagrams.

## Frequently Asked Questions

### What are the four main Archify viewer features?

The Archify viewer provides **Focus** for node-centric inspection and pinning, **Reachability** for analyzing upstream and downstream dependencies, **Route Probing** for finding and animating paths between nodes, and the **Semantic Lens** for browsing individual relationships. These capabilities are implemented in [`viewer/focus.js`](https://github.com/tt-a1i/archify/blob/main/viewer/focus.js) and [`viewer/route-probe.js`](https://github.com/tt-a1i/archify/blob/main/viewer/route-probe.js) using vanilla JavaScript that operates directly on SVG attributes.

### How does Archify compute reachability between nodes?

Archify computes reachability by first extracting edge data from SVG attributes (`data-edge-from`, `data-edge-to`) using `reachabilityRelationships()`, then executing a breadth-first search through `computeReachability()` to determine node depth and connected edges. The `applyReachability()` function marks results in the DOM using `data-reach-match` and `data-reach-depth` attributes while updating the UI counters on the upstream and downstream buttons.

### Can I programmatically trigger route animation in Archify?

Yes, the viewer exposes a public API through `Archify.routeProbe` that allows programmatic control. Call `begin()` to enter selection mode, `chooseStart(id)` to set the origin node, and `choose(id)` to select the destination and trigger the `shortestDirectedPath()` calculation and subsequent animation sequence managed by the motion governor.

### What is the Semantic Lens used for in Archify?

The Semantic Lens displays a focused node's complete relationship set grouped by direction (inbound, outbound, or loop) using `renderRelationshipLens()`. It creates interactive hit targets for each edge that can be inspected via `inspectRelationship()`, enabling users to understand connection semantics without manually tracing SVG lines, while maintaining full keyboard accessibility.