Archify Viewer Animation Trace Mode Usage: Complete Implementation Guide

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) manages a single-budget motion system. When trace mode is active, the governor yields control to the Intent Trace module (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.

<!-- 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, the detection logic validates trace capability using:

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.

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

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

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

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

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

// 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 module checks for active intent traces before playing guided sequences, ensuring trace animations don't conflict with tour animations:

// 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) 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 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.

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