How to Use URL Parameters for Deterministic Screenshots in Archify

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 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 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 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.

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.

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 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 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 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 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 file documents these parameters at lines 106‑108. The actual implementation resides in 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.

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