# Archify Viewer Deep Link URL Parameters: Complete Reference with Examples > Master Archify viewer deep link URL parameters to control views focus playback presentation and theme directly via URLs Learn how to use query strings and hash fragments with examples - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: api-reference - Published: 2026-08-05 --- **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: ```text 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=` 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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app-rendered.html) lines 9897–9901【/archify/examples/web-app-rendered.html†L9897-L9901】 ### `#focus=` Opens the **Semantic Passport** for a specific node, displaying its metadata, relationships, and documentation. The focus explorer automatically copies a deep-link with `#focus=` to the clipboard for sharing. ### `#view=&beat=` 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=&beat=` 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=` | layout preset | Selects a layout preset (used primarily in internal tests) | | `beat=` | 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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 ```html Open node 23 details ``` ### Embedded Autoplay with Theme ```html Play "happy-path" chapter (embedded, dark) ``` ### Presentation Stage Entry ```html Full-screen "consent-boundary" view ``` ### Pinned Beat with Autoplay ```html Autoplay from beat 2 of "rollback-outcomes" ``` 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`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) | Complete specification of deep-link parameters and behavior | | [`archify/examples/web-app-rendered.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery.html) | Live examples demonstrating each pattern | | [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md) & [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/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=` 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.