How to Create Guided Stories and Views in Archify: A Complete Tutorial

Archify converts static diagrams into interactive, step-by-step guided stories using a JSON data definition, build scripts that inject that data into HTML templates, and a runtime UI that renders navigation controls.

The guided stories feature in the tt-a1i/archify repository lets you transform any diagram or collection of views into a narrative experience. Viewers can click through beats, see captions and progress indicators, and copy view metadata. This article walks through the three-layer architecture: data definition, build-time generation, and runtime rendering.

---

What Are Guided Stories in Archify?

A guided story is a sequential presentation of diagram views. Each "beat" in the story displays a specific view, shows a title and optional note, and provides navigation controls. The system supports both standalone guide pages and embedded playback within galleries.

The implementation spans four key source files:

• scripts/guide-template.html — HTML scaffold with placeholders
• scripts/build-guide.mjs — CLI tool for standalone guides
• scripts/build-gallery.mjs — CLI tool for gallery integration
• experiments/mco-showcase/mco-runtime.html — runtime CSS and JavaScript

---

Step 1: Define the Story Data

Create a JSON structure where each entry represents one story beat. The required fields are:

Field	Purpose
viewId	Unique identifier for the view
title	Short caption displayed in the UI
note	Optional description or instruction
viewCount	Number of times this view appears (enables playback detection)

Example entry:

{
  "viewId": "v1",
  "title": "Introduce the core component",
  "note": "Highlight its responsibilities",
  "viewCount": 1
}

Archify provides a helper that extracts this metadata from recipe files. The publicGuideData() function (referenced in the build scripts) collects view information automatically.

---

Step 2: Build the Guided Story Page

Archify ships two CLI scripts for generating guided story outputs.

scripts/build-guide.mjs

This script creates a standalone guide page. It:

1. Reads JSON data from your recipe
2. Substitutes it into scripts/guide-template.html
3. Writes the result to docs/guide.html

The substitution happens at a specific placeholder. In scripts/build-guide.mjs at line 14, the script replaces [[GUIDE_JSON]] with actual data:

// scripts/build-guide.mjs (line 14 context)
// Injects guideData into the template placeholder

The template contains this injection point at line 201:

<!-- scripts/guide-template.html#L201 -->
<script id="guide-data" type="application/json">[[GUIDE_JSON]]</script>

At runtime, the page parses this element. Line 205 of the template shows the parsing logic:

var recipes = JSON.parse(document.getElementById('guide-data').textContent);

Run the builder from your repository root:

node scripts/build-guide.mjs

scripts/build-gallery.mjs

For gallery integration, this script adds a guidedPlayback flag when a view has viewCount > 0. The flag is set at line 308 of scripts/build-gallery.mjs:

// scripts/build-gallery.mjs#L308
// Adds guidedPlayback: true when viewCount is non-zero

Usage:

node scripts/build-gallery.mjs path/to/your/recipe.json

The gallery automatically enables playable guided stories for any diagram with valid story data.

---

Step 3: Runtime UI Rendering

When the generated page loads, Archify's front-end transforms the JSON into interactive controls. The runtime code resides in experiments/mco-showcase/mco-runtime.html.

Navigation Controls

The UI includes:

• Toolbar buttons — play/pause, next, previous, and stop controls per story beat
• Progress bar — visual indicator of current position (.guided-view-progress)
• Captions — title and note display (.guided-story-caption)
• Metadata area — copy-able view IDs and notes

CSS Architecture

The .guided-views family of CSS classes controls visibility and styling. Key implementation points from mco-runtime.html:

• Container definition — line 2204 introduces the guided views container
• Button styling — begins at line 916 with hover and active states
• Blueprint preset — line 2229 shows preset-specific customization: html[data-preset="blueprint"] .guided-views button

State Behaviors

Behavior	Implementation
Play story	data-playing="true" attribute added to .guided-views reveals controls
Motion pause	html[data-motion="still"] selector keeps UI visible (line 823)
Caption toggle	[hidden] attribute controlled by story state (line 2310)

---

Complete Workflow Example

Follow these steps to create and view a guided story:

1. Add metadata to your recipe:

{
  "views": [
    {"viewId":"v1","title":"Introduce the core component","note":"Highlight its responsibilities","viewCount":1},
    {"viewId":"v2","title":"Show data flow","note":"Arrow from A to B","viewCount":1}
  ]
}

2. Generate the guide:

node scripts/build-guide.mjs

3. Open docs/guide.html in a browser. Click the play button to step through views.

4. Optional: embed in a gallery:

node scripts/build-gallery.mjs my-recipe.json

---

Key Source Files Reference

File	Purpose	Line Markers
scripts/guide-template.html	HTML scaffold with [[GUIDE_JSON]] placeholder	L201, L205
scripts/build-guide.mjs	CLI injection script	L14
scripts/build-gallery.mjs	Gallery integration with guidedPlayback flag	L308
experiments/mco-showcase/mco-runtime.html	Runtime UI (CSS/JS)	L2204, L916, L823, L2229, L2310
docs/guide.html	Generated output file	—

---

Summary

• Data layer — JSON with viewId, title, note, and viewCount fields defines each story beat
• Build layer — build-guide.mjs (standalone) and build-gallery.mjs (gallery) inject data into templates
• Runtime layer — CSS classes (.guided-views) and JavaScript in mco-runtime.html render interactive controls
• Integration — gallery builds automatically detect stories via the guidedPlayback flag when viewCount exceeds zero

The [[GUIDE_JSON]] placeholder system in scripts/guide-template.html provides a clean separation between data and presentation, letting you author stories without touching HTML directly.

---

Frequently Asked Questions

How do I enable guided playback in a gallery?

Run scripts/build-gallery.mjs with your recipe path. The script automatically sets guidedPlayback: true (line 308) for any view where viewCount > 0. The gallery UI then displays play controls for those diagrams.

Can I customize the appearance of guided story controls?

Yes. The runtime CSS in experiments/mco-showcase/mco-runtime.html supports preset-based styling. For example, the "blueprint" preset customizes button radius and colors via html[data-preset="blueprint"] .guided-views button (line 2229). Modify these rules or add your own preset selectors.

What happens if a view has viewCount set to zero?

Views with viewCount: 0 or no viewCount field are excluded from guided story generation. The build-gallery.mjs script only activates guidedPlayback when viewCount is non-zero, following the logic at line 308 of the source code.

Where is the story data actually stored in the generated HTML?

The JSON is embedded in a <script> element with id="guide-data" and type="application/json". The build-guide.mjs script replaces the [[GUIDE_JSON]] placeholder at line 201 of scripts/guide-template.html. The runtime parses this element at line 205 using JSON.parse(document.getElementById('guide-data').textContent).

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