Use Vishot With Electron

Use Vishot with Electron

Keep product routes, selectors, window identities, and interaction scenarios in the product repository.

Workflow

1. Identify the Electron package, built main entrypoint, requested window and state, and output directory supplied by the caller.

2. Search for an existing defineScenario module. In AIRI, start with packages/scenarios-stage-tamagotchi-electron.

3. Build the application when its main entrypoint is absent or stale. For a production/file renderer, wait for the repository build command to exit successfully. Pass --settle-ms 2500 so Vishot waits through Vite bundling or renderer reloads; Vishot intentionally has no default delay.

4. Run the product scenario with vishot capture --target electron.

5. When no scenario is needed, use Vishot's direct window capture:

   pnpm exec vishot capture \
     --target electron \
     --app-entrypoint ./path/to/electron-main.js \
     --cwd . \
     --window-url '#/' \
     --settle-ms 2500 \
     --output-dir /absolute/output/main

6. Select a unique window with --window-url or --window-title. Omit both only when the first created window is intentionally the target.

7. If Playwright cannot discover Electron through the package-manager layout, resolve the app package's Electron binary and pass its absolute path with --electron-executable.

8. For a non-default state, create a temporary product scenario or extend the existing product-owned scenario with Playwright actions. Do not add product selectors to this skill.

9. Inspect every screenshot and confirm it depicts the intended window and state.

10. Return its stable ID, title, window identity, and absolute path to $use-vishot or the caller.

Window Sizing

Resize the native BrowserWindow through Playwright's Electron handle when a scenario needs a deterministic content size:

const size = { width: 1200, height: 900 }
const browserWindow = await electronApp.browserWindow(page)

try {
  await browserWindow.evaluate((window, target) => {
    window.setContentSize(target.width, target.height)
  }, size)
}
finally {
  await browserWindow.dispose()
}

await page.waitForFunction(target => (
  globalThis.innerWidth === target.width
  && globalThis.innerHeight === target.height
), size)

• Use BrowserWindow.setContentSize() when the requested dimensions describe the renderer content captured by page.screenshot().
• Use BrowserWindow.setSize() only when the requested dimensions describe the complete native window, including its frame and title bar.
• Do not use page.setViewportSize() to resize an Electron window. It overrides renderer viewport metrics through Playwright/CDP but does not resize the native BrowserWindow, so the visible window and screenshot state can disagree.
• Treat screenshot dimensions as device pixels. On a display with devicePixelRatio = 2, a 1200 × 900 content area normally produces a 2400 × 1800 screenshot.

Electron Windows and UI State

• Do not treat electronApp.firstWindow() or the next window event as semantic window selection. They reflect creation order, and startup may create Chromium DevTools, splash, onboarding, hidden, or auxiliary windows before the intended product window.

• Identify a window with a combination of stable URL or hash route, title, and a state-specific visible locator. Scan electronApp.windows() until one window satisfies the identity predicate, and fail if no exact match appears. A window event alone is also insufficient when the app reuses an existing window.

• Exclude known non-target windows explicitly, such as devtools:// pages or onboarding routes. Select the intended window before changing its hash or route; navigating a wrongly selected renderer can produce a plausible URL with blank or invalid content.

• Treat controls that expand, collapse, auto-hide, or reuse one toggle for both directions as state machines. For a Control Island or similar surface, first check whether the desired child control is visible. Expand only when it is absent, then wait for the child control before clicking it. Recheck immediately before the action when the surface can auto-collapse.

  async function ensureControlsOpen(page) {
    const settingsButton = page.locator('button').filter({
      has: page.locator('[i-solar\\:settings-minimalistic-outline]'),
    }).first()
  
    if (await settingsButton.isVisible().catch(() => false))
      return settingsButton
  
    await page.locator('button').filter({
      has: page.locator('[i-solar\\:alt-arrow-up-line-duotone]'),
    }).first().click({ force: true })
    await settingsButton.waitFor({ state: 'visible' })
    return settingsButton
  }

  Keep this logic product-owned because the icon, lifecycle, and open-state postcondition belong to the application.