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

> Explore Archify's guided views and chapters for interactive diagram walkthroughs. Learn how Archify orchestrates step-by-step navigation and animations in the viewer.

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

---

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

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

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

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