# How to Use URL Parameters for Deterministic Screenshots in Archify

> Learn to use URL parameters like theme=dark and openExport=1 in Archify for deterministic, pixel-perfect screenshots. Ensure reproducible visuals for any Archify diagram.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-14

---

**Append `?theme=dark` (or `light`) and `?openExport=1` to any Archify diagram URL to freeze the visual theme and auto‑open the export menu, ensuring pixel‑perfect reproducibility across manual and automated screenshots.**

Archify renders interactive HTML diagrams that dynamically adapt to system color schemes and require user interaction to reveal export controls. For documentation, visual regression testing, or CI pipelines, you need a way to lock the initial state. The [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) reference implementation exposes URL parameters that override user preferences and trigger UI states programmatically, giving you deterministic rendering without manual clicks.

## Supported URL Parameters

Archify recognizes two query parameters that control the initial render state. These are parsed early in the page lifecycle to prevent visual flashes or layout shifts before capture.

### Theme Override (`theme`)

Add `?theme=light` or `?theme=dark` to force a specific color palette. This overrides both the `localStorage` saved preference and the `prefers-color-scheme` media query.

According to the source code in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) lines 27‑34, the `urlOverride` function inspects `window.location.search` for the `theme` key. If the value is `light` or `dark`, it applies the attribute to the document element immediately, before the first paint cycle. This prevents the brief flash of the opposite theme that would otherwise occur while the JavaScript initializes.

### Auto‑Open Export Menu (`openExport`)

Set `?openExport=1` to trigger the export dropdown automatically on page load. This is essential for capturing the toolbar or the export button itself in headless browser automation.

As implemented in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) lines 95‑100, the export initialization script checks for this parameter after fonts are ready. When present and equal to `"1"`, it programmatically opens the menu by toggling the appropriate CSS class, ensuring the UI is stable before you capture the screenshot.

## Implementation Details in the Source Code

The deterministic behavior relies on two specific blocks in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html).

**Theme Priority Logic:** The `urlOverride` utility (lines 27‑34) gives URL parameters precedence over stored settings. It parses the query string via `URLSearchParams`, validates the value against allowed themes, and applies it synchronously so the correct styles are active during the initial render.

**Export State Initialization:** Lines 95‑100 handle the `openExport` flag. The code waits for the `document.fonts.ready` promise (or falls back to a timeout), then checks `new URLSearchParams(window.location.search).get('openExport')`. If the result is `"1"`, it invokes the menu open handler immediately rather than waiting for user interaction.

These mechanisms are documented in the project README at lines 106‑108, which explains their purpose for scripting consistent screenshots.

## Automating Screenshots with Puppeteer

Combine these parameters with headless browser scripts to generate images in CI pipelines. The URL parameters eliminate the need to simulate clicks or wait for theme transitions.

```javascript
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  
  // Load with forced dark theme and export menu visible
  await page.goto('file:///path/to/diagram.html?theme=dark&openExport=1');
  
  // Wait for the export menu to fully render
  await page.waitForSelector('.export-menu.open');
  
  await page.screenshot({ path: 'archify-screenshot.png', fullPage: true });
  await browser.close();
})();

```

For Playwright, the approach is identical: append the parameters to the `page.goto()` URL and assert on the visibility of the opened export container.

## Summary

- **`?theme=dark` or `?theme=light`** forces the color scheme in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) via the `urlOverride` function (lines 27‑34), preventing theme flashes.
- **`?openExport=1`** auto‑opens the export menu (lines 95‑100), making the toolbar available for capture without manual interaction.
- These parameters enable **reproducible screenshot pipelines** using Puppeteer, Playwright, or manual browser tools.
- The functionality is officially documented in the repository [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) at lines 106‑108.

## Frequently Asked Questions

### What URL parameters does Archify support for screenshots?

Archify supports two parameters in the reference web app: `theme` (accepts `light` or `dark`) and `openExport` (accepts `1`). These are parsed in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) to set the initial visual state before rendering completes.

### How do I prevent the theme from flashing when taking screenshots?

Use the `theme` URL parameter. The `urlOverride` logic at lines 27‑34 of [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) reads this parameter and applies the theme class immediately during script execution, before the browser paints the first frame, eliminating any flash of unstyled or incorrectly‑themed content.

### Can I use these parameters with automated testing tools like Playwright?

Yes. Append `?theme=light&openExport=1` (or your preferred combination) to the file or server URL passed to `page.goto()`. Then wait for the selector `.export-menu.open` to appear before calling `screenshot()`, as the menu animation completes after the font load promise resolves.

### Where is the deterministic screenshot behavior documented in the source code?

The [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) file documents these parameters at lines 106‑108. The actual implementation resides in [`examples/web-web.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-web.html): theme override logic appears at lines 27‑34 inside the `urlOverride` function, while the export auto‑open logic is located at lines 95‑100.