Archify Viewer Deep Link URL Parameters: Complete Reference with Examples

Archify viewer deep link URL parameters let you control views, focus, playback, presentation mode, and theme directly from URLs using query strings and hash fragments.

The Archify viewer is a web-based architecture visualization tool that accepts URL parameters to drive the initial state without manual interaction. These deep links are implemented in the runtime HTML files and generated by build scripts in the tt-a1i/archify repository. This guide covers every supported parameter, its function, and how the viewer processes them.

---

URL Structure Overview

Archify deep links combine query strings (?key=value) and hash fragments (#key=value) in a single URL:

artifact.html?present=1&play=1&theme=dark#view=chapter-1&beat=step-3
│              │      │      │         │    │            │
│              │      │      │         │    │            └── Hash: specific beat
│              │      │      │         │    └── Hash: named view
│              │      │      │         └── Hash separator
│              │      │      └── Query: theme override
│              │      └── Query: autoplay flag
│              └── Query: presentation mode flag
└── Base artifact file

---

Hash Fragment Parameters (#…)

Hash fragments control navigation state and are updated dynamically as users interact with the viewer.

#view=<view-id>

Loads a named view — a guided chapter defined in meta.views within the artifact's metadata.

The viewer searches meta.views for a matching ID, restores that view's camera position and node visibility, and updates the browser history via history.replaceState so the URL reflects the current chapter.

Implementation: archify/examples/web-app-rendered.html lines 9897–9901【/archify/examples/web-app-rendered.html†L9897-L9901】

#focus=<node-id>

Opens the Semantic Passport for a specific node, displaying its metadata, relationships, and documentation.

The focus explorer automatically copies a deep-link with #focus=<node-id> to the clipboard for sharing.

#view=<view-id>&beat=<node-id>

Pins a specific beat (moment) inside a named view without autoplaying.

The viewer restores the view and positions the beat marker at the specified node, pausing for user inspection.

#view=<view-id>&beat=<node-id> with ?play=1

Combines beat pinning with autoplay — the story plays only the remaining beats after the selected moment.

---

Query String Parameters (?…)

Query strings configure rendering mode and behavior before the viewer initializes.

Parameter	Value	Function
present=1	(none)	Opens the Presentation Stage — a full-screen, viewport-filling view that preserves theme, focus, and zoom state
play=1	(none)	Starts autoplay of the current guided view or pinned beat
embed=1	(none)	Hides UI controls (toolbar, navigation arrows) for clean embedded integration
theme=dark / theme=light	dark or light	Forces the viewer's color theme regardless of system preference
layout=<type>	layout preset	Selects a layout preset (used primarily in internal tests)
beat=<node-id>	node ID	Alternative to hash syntax for backward compatibility

Implementation: URL builders in scripts/build-gallery.mjs line 201 construct parameter combinations like ?present=1&play=1#view=...【/scripts/build-gallery.mjs†L201-L202】. The README documents these at lines 272–282【/README_EN.md†L272-L282】 and the CHANGELOG at lines 72–90【/CHANGELOG.md†L72-L90】.

---

Common Deep Link Patterns

URL Pattern	Result
?embed=1&play=1&theme=dark#view=happy-path	Embedded player, dark theme, autoplay "happy-path" chapter
?present=1#view=request-boundary	Full-screen Presentation Stage on "request-boundary" view
?play=1#view=order-transit&beat=step-3	Autoplay "order-transit" starting at beat "step-3"
#focus=node-42	Open Semantic Passport for node "node-42" immediately

These patterns appear throughout docs/gallery.html lines 345–607【/docs/gallery.html†L345-L607】 as "Play named chapter ↗" links.

---

Parameter Processing Pipeline

The viewer applies parameters in strict order:

1. Parse query string — Extract present, play, embed, theme, layout, and beat parameters
2. Parse hash fragment — Extract view, focus, and beat (hash takes precedence over query beat)
3. Apply theme — Switch CSS classes before first render to prevent flash
4. Restore view — Execute view-loader with #view= against meta.views
5. Focus or pin beat — Center camera on node for #focus= or &beat=
6. Set entry mode — Activate Presentation Stage (present=1), hide chrome (embed=1), or start scheduler (play=1)

The history.replaceState calls in archify/examples/web-app-rendered.html【/archify/examples/web-app-rendered.html†L9897-L9901】 maintain URL sync during user navigation.

---

Code Examples

Basic Focus Link

<a href="gallery/artifacts/web-app.architecture.html#focus=node-23">
  Open node 23 details
</a>

Embedded Autoplay with Theme

<a href="gallery/artifacts/agent-tool-call.workflow.html?embed=1&play=1&theme=dark#view=happy-path">
  Play "happy-path" chapter (embedded, dark)
</a>

Presentation Stage Entry

<a href="gallery/artifacts/product-analytics.dataflow.html?present=1#view=consent-boundary">
  Full-screen "consent-boundary" view
</a>

Pinned Beat with Autoplay

<a href="gallery/artifacts/deployment-release.lifecycle.html?play=1#view=rollback-outcomes&beat=step-2">
  Autoplay from beat 2 of "rollback-outcomes"
</a>

These patterns are generated by scripts/build-readme-showcase.mjs line 102【/scripts/build-readme-showcase.mjs†L102-L103】.

---

Key Source Files

File	Purpose
archify/references/viewer-runtime.md	Complete specification of deep-link parameters and behavior
archify/examples/web-app-rendered.html	Runtime implementation with hash handling and history.replaceState
scripts/build-gallery.mjs	URL construction with parameter combinations
docs/gallery.html	Live examples demonstrating each pattern
README_EN.md & CHANGELOG.md	Product documentation of deep-link capabilities

---

Summary

• Hash fragments (#view=, #focus=, &beat=) control navigation state and sync with browser history
• Query strings (?present=, ?play=, ?embed=, ?theme=) configure rendering mode at load time
• Combine both for precise control: ?present=1&play=1#view=chapter&beat=moment
• The viewer processes parameters in fixed sequence: query → hash → theme → view → focus/beat → entry mode
• All functionality is implemented in runtime HTML files and generated by build scripts in tt-a1i/archify

---

Frequently Asked Questions

What is the difference between ?beat= and #view=&beat=?

?beat= is a legacy query parameter maintained for backward compatibility. #view=&beat= is the modern hash-based approach that associates a beat with a specific view and enables proper browser history tracking. Hash beats also support ?play=1 for autoplay from that moment.

Can I use present=1 and embed=1 together?

Yes, but present=1 takes precedence. The Presentation Stage is a specialized full-screen mode that already minimizes UI chrome, so embed=1 has no additional effect when present=1 is active.

How do I link directly to a node's Semantic Passport?

Append #focus=<node-id> to any artifact URL. The viewer immediately opens the focus explorer for that node and copies a shareable link to the clipboard. No query parameters are required.

Does the theme parameter override user preferences?

Yes. ?theme=dark or ?theme=light forces the specified theme regardless of prefers-color-scheme or previously stored user settings. The CSS classes are switched before initial render to prevent theme flashing.

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