Archify Guided Views and Chapters in the Viewer: Interactive Diagram Walkthroughs

TLDR: Archify's viewer implements guided views by parsing a JSON chapter array from hidden HTML script tags, validating node IDs against the SVG, and orchestrating step-by-step navigation through delta-based handoff animations coordinated by a motion governor.

The tt-a1i/archify repository provides a client-side diagram viewer that transforms static SVGs into interactive narratives through guided views and chapters. This feature allows authors to define sequences of focused node sets that viewers can navigate manually or play as automated stories. The entire implementation resides in the viewer package, requiring no server interaction and enabling export as self-contained HTML files.

Data Loading and Chapter Validation

Archify guided views begin with data embedded directly in the HTML. A hidden <script> element with the ID #archify-guided-views-data contains a JSON array describing each chapter's label, optional note, and target node IDs.

In viewer/guided-views.js, the module parses this data immediately on load. According to the source code at line 2, the script extracts the JSON content and validates it against the current SVG. The validation loop around lines 66-77 builds a canonicalNodeIds array and filters each view.focus property to ensure only existing node IDs are retained, eliminating duplicates and preventing navigation errors.

Constructing the Chapter Interface

Once validated, the viewer constructs the navigation UI within the #guided-views panel. The panel.setAttribute('data-active-view', 'all') call and buildChapterIndex() invocation occur near lines 81-86, initializing the interface.

The buildChapterIndex function, defined from lines 97-142, generates accessible chapter controls. For each entry, it creates <li><button> elements with comprehensive ARIA attributes (aria-label, aria-current), numeric indices, chapter titles, and counts of focused nodes. This structure ensures screen readers can navigate the diagram story effectively.

Navigation and Handoff Animation

Chapter transitions use a sophisticated handoff animation system. When users click a chapter button or use prev/next controls, the beginHandoff function (lines 172-225) executes.

The system first calculates the transition delta. chapterDelta (lines 97-108) determines which nodes stay, enter, or leave the focus set, while chapterAnchor (lines 111-121) selects the reference point for the animation. If motion is permitted, drawHandoffAnchor (lines 146-165) creates a temporary highlight overlay on the anchor node before the camera pans.

All animations respect user preferences through Archify.motionGovernor. The viewer checks reducedMotion() (lines 87-89) and handoffMotionAllowed (lines 123-130) to honor prefers-reduced-motion settings. The governor claim occurs around lines 254-258, ensuring handoffs can be globally paused or cancelled.

Story Playback and Shareable Moments

Automatic playback transforms chapters into self-running presentations. When activated, setAutoplayState and startShareCueProgress (lines 507-526) initiate an interval defined by VIEW_INTERVAL_MS = 3200 milliseconds. The setStoryBeat function (lines 779-828) updates captions, progress bars, and optionally pulses edges via pulseStoryStep at each interval.

Authors and readers can create shareable links to specific moments. The storyMomentLink function (lines 551-558) encodes the current view ID and beat index into the URL hash (view= and beat= parameters). The copyStoryMomentLink method (lines 801-812) writes this URL to the clipboard, enabling deep linking to any step in the narrative.

Preview and Accessibility Features

While the viewer is idle, hovering over chapter buttons triggers a preview mode. The showChapterPreview (lines 440-466) and syncChapterPreview (lines 468-475) functions calculate deltas without committing the handoff, applying CSS classes via data-chapter-preview-role to temporarily highlight upcoming focus sets.

Accessibility remains integral throughout. The syncChapterIndex (lines 444-493) and renderStoryCaption (lines 723-745) functions dynamically update aria-live regions and aria-current states whenever the active chapter changes. This ensures assistive technologies announce transitions and current position within the story sequence.

Implementation Examples

Defining Chapters in HTML

Embed the chapter data as a JSON array in a hidden script tag:

<script id="archify-guided-views-data" type="application/json">
[
  {
    "id": "intro",
    "label": "Intro",
    "note": "Show the entry point",
    "focus": ["node-1"]
  },
  {
    "id": "api-path",
    "label": "API Path",
    "focus": ["node-1","node-2","node-3"]
  },
  {
    "id": "final-state",
    "label": "Final State",
    "focus": ["node-4"]
  }
]
</script>

The guided-views.js module parses this configuration on initialization (line 64) to build the interactive interface.

Programmatic Navigation

Jump to specific chapters or control playback via the global API:

// Navigate to the second chapter (index 1)
Archify.guidedViews().active().setActiveIndex(1);

// Start automatic playback of the current chapter
document.getElementById('guided-view-play').click();

The setActiveIndex method internally calls setStoryBeat to update SVG attributes, captions, and progress indicators.

Generating Deep Links

Create shareable URLs that reference specific story moments:

// Copy a link to the third beat of the current chapter
Archify.guidedViews().copyStoryMomentLink()
  .then(copied => console.log('Link copied:', copied));

This encodes the current state into the URL hash, allowing recipients to jump directly to that specific diagram context.

Summary

• Archify guided views serialize diagram narratives into JSON chapter arrays embedded in HTML, parsed by viewer/guided-views.js.
• The system validates node IDs against the SVG DOM (lines 66-77) before constructing an accessible UI with ARIA-compliant navigation controls.
• Handoff animations use delta calculations (chapterDelta, chapterAnchor) and temporary overlays (drawHandoffAnchor) to transition between focus sets smoothly.
• A motion governor integrates with prefers-reduced-motion to respect accessibility preferences and enable global pause functionality.
• Story playback advances at 3200ms intervals via setStoryBeat, while storyMomentLink generates hash-based URLs for sharing specific narrative states.
• The architecture remains entirely client-side, enabling deployment as static HTML without server dependencies.

Frequently Asked Questions

How does Archify validate that chapter nodes exist in the diagram?

The viewer filters chapter data during initialization. In guided-views.js, the code builds a canonicalNodeIds array and validates each ID in view.focus against the current SVG (lines 66-77). Only existing nodes are retained, ensuring navigation targets are always present in the rendered diagram.

What controls the timing and motion of chapter transitions?

The motion governor (Archify.motionGovernor) coordinates all animations. Transitions check handoffMotionAllowed (lines 123-130) and reducedMotion() (lines 87-89) to respect prefers-reduced-motion settings. Playback intervals are governed by VIEW_INTERVAL_MS (3200ms), while the governor manages animation tokens to prevent conflicts and enable pausing.

Can users share links to specific steps in a guided view?

Yes. The storyMomentLink function (lines 551-558) encodes the current view ID and beat index into URL hash parameters (view= and beat=). The copyStoryMomentLink method writes this to the clipboard, creating deep links that open the diagram at the exact narrative step referenced.

How does the viewer handle accessibility for screen reader users?

All controls expose semantic markup including aria-label, aria-live, and aria-current attributes. The syncChapterIndex (lines 444-493) and renderStoryCaption (lines 723-745) functions dynamically update these attributes as users navigate chapters, announcing state changes and current position in the story sequence.

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