# Archify Viewer Animation Trace Mode Usage: Complete Implementation Guide

> Unlock Archify viewer animation trace mode with this guide. Learn how to visualize semantic flow by setting data-animation trace on SVG containers and control animations with hover and focus.

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

---

**Archify's trace animation mode visualizes semantic flow across diagrams by setting `data-animation="trace"` on the SVG container, which triggers the Motion Governor to yield animation control to the Intent Trace module when nodes are hovered or focused.**

The Archify viewer in the `tt-a1i/archify` repository provides sophisticated animation capabilities for diagram visualization. This guide explains how to implement and control the **trace animation mode**, which temporarily visualizes intent, focus, and semantic relationships through dynamic overlays coordinated by the Motion Governor.

## What Is Trace Animation Mode?

Trace animation mode in Archify creates temporary visual overlays that illustrate the flow of intent and focus across diagram nodes. When activated, the system builds a one-hop topology around selected nodes, cloning incident edges into an overlay layer that animates according to directional flow.

The mode operates through a cooperative ownership model where the **Motion Governor** ([`viewer/motion-governor.js`](https://github.com/tt-a1i/archify/blob/main/viewer/motion-governor.js)) manages a single-budget motion system. When trace mode is active, the governor yields control to the **Intent Trace** module ([`viewer/intent-trace.js`](https://github.com/tt-a1i/archify/blob/main/viewer/intent-trace.js)), pausing ambient animations while the semantic trace visualization renders.

## Enabling Trace Capability

To activate trace mode, add the `data-animation="trace"` attribute to your SVG container element. The Motion Governor detects this capability during initialization by checking the SVG element's attributes.

```html
<!-- Enable trace mode in the viewer HTML template -->
<svg class="diagram" data-animation="trace" viewBox="0 0 800 600">
  <!-- Diagram content -->
</svg>

```

In [`viewer/motion-governor.js`](https://github.com/tt-a1i/archify/blob/main/viewer/motion-governor.js), the detection logic validates trace capability using:

```javascript
const capable = !!(svg && svg.getAttribute('data-animation') === 'trace');

```

Once detected, the governor initializes an ambient animation batch via `startAmbient()`, preparing the viewer to handle semantic owner transitions.

## The Motion Governor Architecture

The Motion Governor serves as the central coordinator for animation states in the Archify viewer. It manages transitions between ambient motion and owner-specific animations like intent traces.

### Detecting Trace Capability and Ownership

The governor's `deriveOwner()` method checks for active semantic owners by inspecting DOM attributes. When an intent trace is active, the SVG element carries the `data-intent-trace-active` attribute containing the selected node ID.

```javascript
// The governor checks for intent-trace ownership
if (svg.hasAttribute('data-intent-trace-active')) {
  // Yields control to intent trace animation
  return 'intent';
}

```

This ownership detection triggers the governor to mark the viewer's motion state as **still**, pausing ambient animations while the trace overlay renders.

### Managing Ambient Motion States

The governor provides methods to programmatically control animation playback through the `Archify.motionGovernor` API:

```javascript
// Pause ambient motion manually
Archify.motionGovernor.setPaused(true);

// Resume ambient motion
Archify.motionGovernor.setPaused(false);

```

When the intent trace clears, the governor automatically resumes ambient motion if no other semantic owners remain active.

## The Intent Trace Overlay System

The Intent Trace module ([`viewer/intent-trace.js`](https://github.com/tt-a1i/archify/blob/main/viewer/intent-trace.js)) constructs temporary visual overlays that highlight node relationships. It creates a dedicated overlay group within the SVG that sits above the base diagram layers.

### Rendering Traces with show()

When a user hovers over or keyboard-focuses a node, the `show(id)` method constructs the trace visualization:

1. Creates an overlay element `<g class="intent-trace-overlay">`
2. Clones incident edges with directional styling via `intent-trace-flow` class
3. Sets `data-direction` attributes (`out`, `in`, or `loop`) on edge elements
4. Injects the overlay before the first existing edge or node in the SVG
5. Updates `data-intent-trace-active` with the selected node ID

```javascript
// Display intent trace for a specific node
Archify.intentTrace.show('node-42', { announce: true });

```

The `announce` option enables accessibility features while triggering the visual overlay.

### Clearing the Trace Overlay

To remove the trace visualization and return control to ambient motion:

```javascript
// Programmatically clear the trace
Archify.intentTrace.clear();

```

The `clear()` method removes the overlay group, deletes the `data-intent-trace-active` attribute, and signals the Motion Governor to resume ambient animation budgeting.

## Practical Implementation Examples

### Basic Trace Activation

Enable trace mode in your HTML template and programmatically trigger traces:

```html
<svg id="archify-viewer" data-animation="trace">
  <!-- Diagram nodes and edges -->
</svg>

<script>
  // Show trace when user selects a node
  document.getElementById('archify-viewer').addEventListener('click', (e) => {
    if (e.target.dataset.nodeId) {
      Archify.intentTrace.show(e.target.dataset.nodeId);
    }
  });
</script>

```

### Checking Motion State

Query the current animation state for UI toggle synchronization:

```javascript
// Check if motion is paused by an active trace
const isPaused = document.documentElement.getAttribute('data-motion') === 'still';

```

### Integration with Guided Views

The [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) module checks for active intent traces before playing guided sequences, ensuring trace animations don't conflict with tour animations:

```javascript
// Guided views verify no active owners before proceeding
if (!svg.hasAttribute('data-intent-trace-active')) {
  // Safe to play guided view sequence
}

```

## Summary

- **Trace mode requires** the `data-animation="trace"` attribute on the SVG container to enable Motion Governor detection.
- **The Motion Governor** ([`viewer/motion-governor.js`](https://github.com/tt-a1i/archify/blob/main/viewer/motion-governor.js)) manages animation ownership, yielding to intent traces when `data-intent-trace-active` is present.
- **Intent Trace overlays** are temporary SVG groups created by `Archify.intentTrace.show()`, cloning edges with directional flow styling.
- **Cleanup is automatic** when calling `Archify.intentTrace.clear()`, which removes the overlay and resumes ambient motion.
- **Programmatic control** is available through `Archify.motionGovernor.setPaused()` for manual animation management.

## Frequently Asked Questions

### How do I enable trace animation mode in Archify?

Add the `data-animation="trace"` attribute to your SVG container element. The Motion Governor automatically detects this capability during initialization in [`viewer/motion-governor.js`](https://github.com/tt-a1i/archify/blob/main/viewer/motion-governor.js) and prepares the single-budget motion model for owner transitions.

### What happens to ambient animations when an intent trace is active?

The Motion Governor pauses ambient motion and sets the motion state to `still` when it detects the `data-intent-trace-active` attribute. The Intent Trace module owns the animation budget until `clear()` removes the overlay and the attribute, allowing the governor to resume ambient animations.

### Can I trigger intent traces programmatically without user interaction?

Yes. Call `Archify.intentTrace.show(nodeId, options)` directly from your JavaScript. The method accepts a node identifier string and an options object with an `announce` boolean. This is useful for deep-linking to specific diagram states or integrating with external navigation controls.

### Where does the trace overlay render in the SVG DOM?

The Intent Trace module injects the `<g class="intent-trace-overlay">` element immediately before the first existing edge or node element in the SVG container. This positioning ensures the trace visualization appears above the base diagram while maintaining proper z-index layering within the SVG structure.