# What Are Guided Views and Stories in Archify? A Complete Guide to Interactive Diagram Navigation > Explore Archify's Guided Views and Stories for interactive diagram navigation. Pre-define camera positions and animations for step-by-step exploration via URL. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-08-07 --- **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`](https://github.com/tt-a1i/archify/blob/main/archify-example.json): ```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=` loads and animates to the matching view on page load 2. **UI panel** – The *Guided Views* container (in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/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: ```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`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-33.md)) ### How Guided Stories Are Triggered Stories respond to hash patterns and UI controls: - **`#story=`** – Load story at beat 0, ready for playback - **`#story=&beat=`** – 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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) shows the container pattern: ```html ``` --- ## 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`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-37.md) under "Guided Views, Story Trail, Story Beats," while [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) tracks recent playback improvements. --- ## Summary - **Guided Views** provide discrete, named camera positions defined in `meta.views` and triggered via `#view=` 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`](https://github.com/tt-a1i/archify/blob/main/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=` 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`](https://github.com/tt-a1i/archify/blob/main/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.