Stable URL Fragments for Deep Linking in Archify: The Complete Reference

Archify employs stable hash fragments such as #view=<view-id> and #view=<view-id>&beat=<node-id> alongside query parameters including ?present=1, ?play=1, ?embed=1, and ?theme=dark to create persistent deep links that resolve to specific visual states, views, and presentation modes across all deployments.

The tt-a1i/archify repository implements a deterministic deep-linking architecture that maps specific URL fragments to named views and semantic nodes within architecture artifacts. These stable URL fragments for deep linking form a public contract defined in the documentation source files, ensuring that shared links remain valid and resolve to identical visual states regardless of deployment environment or version updates.

Hash Fragment Syntax for View Navigation

Archify's deep-linking grammar centers on hash fragments parsed from the URL to identify specific locations within an artifact. According to docs/research-visual-evolution-round-33.md, these fragments follow a strict syntax that enables both broad view selection and precise beat-level navigation.

Selecting Named Views (#view=<view-id>)

The primary fragment selects a named view or chapter within an artifact. Appending #view=happy-path to an artifact URL instructs Archify to render the specific view identified by that slug, isolating the relevant section of the architecture documentation.

Pinning Specific Beats (#view=<view-id>&beat=<node-id>)

For granular navigation, combine the view identifier with a beat parameter to target a specific semantic node. The fragment #view=request-path&beat=fetch-data simultaneously selects the "request-path" view and pins the "fetch-data" beat, scrolling to or highlighting that exact moment in the visualization.

Query Parameters for Presentation Control

Beyond hash fragments, Archify recognizes several query parameters that control how the artifact renders. These parameters, documented in docs/gallery.html and docs/index.html, modify the UI state without changing the underlying view selection.

Presentation Mode (?present=1)

Appending ?present=1 activates full-screen presentation mode, hiding the editor UI and chrome to provide a clean view suitable for demonstrations. This parameter works in conjunction with view fragments to open a specific chapter in a presentation-ready state.

Autoplay (?play=1)

The ?play=1 parameter initiates automatic playback of the selected view upon load. When combined with ?present=1, this creates a one-shot playback link that immediately begins animating through the architecture sequence without user interaction.

Embedding (?embed=1)

Use ?embed=1 to generate iframe-compatible URLs that load the artifact with UI controls hidden. This parameter, utilized in docs/index.html for the landing page proof-of-concept, produces links suitable for integration into external documentation or blog posts.

Theme Control (?theme=<value>)

The ?theme=dark or ?theme=light parameter forces a specific visual theme regardless of system preferences. This ensures consistent styling when embedding artifacts in controlled environments or matching external site aesthetics.

Combining Fragments for Complex Scenarios

Archify processes hash fragments and query parameters independently, allowing arbitrary combinations to construct sophisticated deep links. For example, ?embed=1&play=1&theme=dark#view=happy-path generates an embedded link that automatically plays the "happy-path" view using the dark theme.

The following HTML demonstrates practical combinations:

<!-- Static link to a specific view -->
<a href="gallery/artifacts/web-app.architecture.html#view=request-path">
  Open "Request Path" view
</a>

<!-- Auto-playing presentation link -->
<a href="gallery/artifacts/web-app.architecture.html?present=1&play=1#view=request-path">
  Play "Request Path" chapter
</a>

<!-- Deep link to a specific beat -->
<a href="gallery/artifacts/web-app.architecture.html#view=request-path&beat=fetch-data">
  Jump to "Fetch Data" beat
</a>

<!-- Embedded iframe with dark theme -->
<iframe src="gallery/artifacts/web-app.architecture.html?embed=1&play=1&theme=dark#view=request-path"
        width="800" height="600" sandbox="allow-scripts">
</iframe>

Implementation Verification in Source Code

The stability of these URL fragments is enforced through the build and test pipeline. The script scripts/build-readme-showcase.mjs programmatically assembles URLs containing #view= fragments and query flags, demonstrating production usage of the deep-linking contract.

Additionally, archify/test/real-repository-proof.test.mjs contains automated assertions that verify generated URLs include the expected deep-link fragments, ensuring that refactoring cannot accidentally break the public URL API. These tests validate that fragments such as view= and beat= maintain their defined semantics across builds.

Summary

• Stable URL fragments in Archify combine hash-based view selection (#view=) with optional beat pinning (&beat=) to enable precise navigation into specific architectural states.
• Query parameters control presentation mode (present=1), autoplay (play=1), embedding (embed=1), and theming (theme=dark), all documented in docs/gallery.html.
• Fragment stability is contractually guaranteed and verified by archify/test/real-repository-proof.test.mjs, ensuring long-term link compatibility across versions.
• Complex states are achieved by combining query strings with hash fragments, processed independently by the Archify renderer to produce persistent, shareable links.

Frequently Asked Questions

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

The #view=<view-id> fragment selects an entire named chapter or visualization state, while the &beat=<node-id> parameter appended to a view hash pinpoints a specific semantic moment or node within that view. You must specify a view before targeting a beat, as beats exist within the scope of their parent view.

How do I create a link that opens in presentation mode automatically?

Append ?present=1 as a query parameter before the hash fragment, such as ?present=1#view=happy-path. To also start playback immediately, add &play=1, resulting in ?present=1&play=1#view=happy-path, which loads the view in full-screen mode and begins the sequence automatically.

Are these URL fragments guaranteed stable across Archify versions?

Yes, according to docs/research-visual-evolution-round-33.md, these fragments constitute a public contract. The repository's test suite in archify/test/real-repository-proof.test.mjs programmatically verifies fragment stability, ensuring that links containing #view= and related parameters remain valid across updates unless explicitly deprecated in a major version migration guide.

Can I combine multiple query parameters with hash fragments?

Absolutely. Archify processes query parameters independently of hash fragments, allowing combinations like ?embed=1&play=1&theme=dark#view=request-path&beat=fetch-data. This flexibility enables embedded, auto-playing, themed views pinned to specific beats for sophisticated documentation scenarios.

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