What Are Guided Views and Stories in Archify? A Complete Guide to Interactive Diagram Navigation

Guided Views and Guided Stories in Archify are navigation features that let authors pre-define camera positions and animated sequences, enabling step-by-step exploration of complex diagrams through URL-driven state and a non-print UI panel.

Archify's visualization engine provides guided navigation as a core capability for diagram authors. Instead of leaving viewers to pan and zoom manually, you can encode exactly how someone should experience a diagram—whether through discrete bookmarks or automated storytelling. This article explains both mechanisms as implemented in the tt-a1i/archify repository, including their JSON schema, runtime behavior, and practical usage.

---

Guided Views: Named Camera Positions for Instant Navigation

Guided Views are authored, named viewport configurations that viewers can jump to instantly.

Each view captures a specific camera rectangle—position and zoom level—along with optional metadata like a title or description. When activated, the runtime animates the diagram camera to that exact framing.

How Guided Views Are Defined

Views live in the diagram's JSON under meta.views. As shown in archify-example.json:

{
  "meta": {
    "views": [
      {
        "id": "overview",
        "title": "Overview",
        "camera": { "x": 0, "y": 0, "width": 800, "height": 600 }
      },
      {
        "id": "detail-node-A",
        "title": "Node A Detail",
        "camera": { "x": 1200, "y": 300, "width": 400, "height": 300 }
      }
    ]
  }
}

Each entry requires:

• id – URL-safe identifier used for deep linking
• camera – Object with x, y, width, height defining the viewport rectangle
• title / description – Optional human-readable labels

How Guided Views Are Triggered

Views activate through two paths:

1. URL hash – #view=<view-id> loads and animates to the matching view on page load
2. UI panel – The Guided Views container (in examples/web-app.html) renders clickable buttons for each defined view

The runtime handler onGuidedMotionChange processes hash changes and coordinates camera animation. This handler appears around line 10090 in the example HTML files.

---

Guided Stories: Linear Narratives Through Your Diagram

Guided Stories (also called Story Trails) automate multi-step presentations with sequential camera movements and optional pauses.

Stories are ideal for tutorials, walkthroughs, or any scenario where you want to control the viewer's journey through time and space.

How Guided Stories Are Defined

Stories use meta.story or meta.stories in the diagram JSON:

{
  "meta": {
    "stories": [
      {
        "id": "walkthrough",
        "title": "Feature Walk-through",
        "beats": [
          { "view": "overview", "pause": false },
          { "view": "detail-node-A", "pause": true },
          { "view": "detail-node-B", "pause": false }
        ]
      }
    ]
  }
}

Each beat specifies:

• view – References a view ID (or inline camera data)
• pause – When true, story playback halts for manual inspection
• Additional actions like copy-moment (documented in docs/research-visual-evolution-round-33.md)

How Guided Stories Are Triggered

Stories respond to hash patterns and UI controls:

• #story=<story-id> – Load story at beat 0, ready for playback
• #story=<story-id>&beat=<n> – Jump directly to beat n
• Play button – In the Guided Story panel, advances through beats automatically, respecting pause flags

The same onGuidedMotionChange engine handles story state transitions, monitoring URL hash changes and updating the camera accordingly.

---

Shared Runtime Engine: Guided Motion

Both features rely on Archify's guided-motion system with these characteristics:

Aspect	Implementation
Media query	Watches (--guided-motion) CSS custom property
Print behavior	Panels carry no-print class; excluded from PDF exports
State source	URL hash is single source of truth for view/story/beat
Accessibility	ARIA labels on containers (aria-label="Guided diagram views")

The HTML structure in examples/web-app.html shows the container pattern:

<div class="guided-views no-print" id="guided-views" hidden 
     aria-label="Guided diagram views">
  <span>Guided views</span>
  <!-- Runtime populates from meta.views -->
</div>

<div class="guided-story no-print" id="guided-story" hidden 
     aria-label="Guided story controls">
  <span>Guided story</span>
  <!-- Play/pause injected by runtime -->
</div>

---

Why Guided Views and Stories Matter

• Consistent experience – Same navigation across browsers, devices, and sessions
• Shareable moments – URLs like #view=overview or #story=demo&beat=3 link directly to specific diagram states
• Clean exports – UI panels hide automatically for print/PDF output
• Extensible schema – Add custom beat actions without modifying core runtime

Design rationale appears in docs/research-visual-evolution-round-37.md under "Guided Views, Story Trail, Story Beats," while CHANGELOG.md tracks recent playback improvements.

---

Summary

• Guided Views provide discrete, named camera positions defined in meta.views and triggered via #view=<id> or UI panel
• Guided Stories create linear narratives through meta.stories with sequential beats, pauses, and automatic playback
• Both use the guided-motion engine in examples/web-app.html, respect no-print media constraints, and maintain state in URL hash
• The JSON schema supports extensibility for custom actions while keeping runtime compatibility

---

Frequently Asked Questions

How do I create a deep link to a specific diagram view?

Append #view=<your-view-id> to any Archify diagram URL. For example: https://example.com/diagram.html#view=detail-node-A. The runtime parses this hash on load and animates directly to that camera position.

Can I combine Guided Views and Stories in the same diagram?

Yes. The meta object supports both views and stories arrays simultaneously. Stories often reference view IDs in their beats, creating a layered navigation system where discrete bookmarks feed into longer narratives.

What happens if a story beat references a missing view?

The runtime falls back to inline camera data if provided, or skips the beat gracefully. Per CHANGELOG.md, recent versions improved error handling for malformed story references.

Why don't the guided panels appear in my PDF export?

Both panels use the no-print CSS class, ensuring they remain interactive on screen but invisible in printed or exported documents. This is intentional—keeping exported assets clean while preserving navigation functionality.

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