Vishot

Composable screenshot tooling for source capture, browser rendering, and desktop mockup composition.

Vishot separates screenshot production into reusable source adapters, browser renderers, and mockup primitives. Product-specific scenario automation belongs in the product repository. Vishot owns shared capture protocols, artifact behavior, renderers, and generic visual shells.

Table of Contents

• Installation and Usage
• Concepts
• Packages
• Documentation Automation
• Development
• Status
• License

Installation and Usage

Install the CLI in a project that owns screenshot scenarios:

pnpm add -D @vishot/cli

Use vishot capture when a scenario needs to collect source screenshots from a running application. The Electron adapter launches the application through Playwright Electron and writes raw capture artifacts:

pnpm exec vishot capture \
  --target electron \
  ./capture/scenario.ts \
  --app-entrypoint ./dist/main.js \
  --output-dir ./screenshots/raw

For a direct Electron window capture, omit the scenario and select a window by URL or title. The artifact name defaults to the window title, then its URL route:

pnpm exec vishot capture \
  --target electron \
  --app-entrypoint ./dist/main.js \
  --window-url '#/' \
  --settle-ms 1000 \
  --output-dir ./screenshots/main

Playwright normally discovers the consumer project's Electron binary. In strict or isolated package layouts, pass --electron-executable /absolute/path/to/electron explicitly.

Capture any locally served web or Capacitor route directly. The artifact name defaults to the final URL path or hash-route segment:

pnpm exec vishot render \
  --target browser \
  http://127.0.0.1:5173/settings \
  --width 1440 \
  --height 900 \
  --settle-ms 1000 \
  --output-dir ./screenshots/settings

Direct URL capture does not click or otherwise interact with the page. Use a product-owned scenario when navigation or state setup requires actions.

Use vishot render with a Vite scene app directory when the page exposes Vishot capture roots and needs final composed artifacts:

pnpm exec vishot render \
  --target browser \
  ./capture/scene-app \
  --output-dir ./screenshots/final

Filter browser capture roots by name when a render entry exposes multiple outputs:

pnpm exec vishot render \
  --target browser \
  ./capture/scene-app \
  --output-dir ./screenshots/final \
  --root hero \
  --root settings

Concepts

Vishot keeps capture concerns split across a small protocol:

• Source capture collects raw screenshots from an application runtime.
• Capture roots mark browser-rendered DOM regions that should be exported as final artifacts.
• Ready signals let scenarios and renderers wait until a scene is stable before taking screenshots.
• Artifacts describe generated files with kind, stage, format, dimensions, and paths.
• Mockup primitives provide reusable Vue components for desktop screenshots without owning product routes or product-specific selectors.

Keep application routes, window names, walkthroughs, and AIRI-specific automation outside this repository. Put that logic in the product repository and depend on Vishot packages for the reusable pieces.

Packages

• @vishot/cli: unified command line interface for source capture and browser rendering.
• @vishot/core: shared artifact contracts, capture-root selectors, ready signals, and file helpers.
• @vishot/source-electron: Playwright Electron source capture for raw application screenshots.
• @vishot/renderer-browser: Playwright Chromium renderer for final browser-composed image artifacts.
• @vishot/mockup-desktop-vue: Vue components for capture canvases and desktop mockup shells.

Documentation Automation

The table of contents above is generated with doctoc so README navigation is not hand-written. Run this after changing root README headings:

pnpm docs:update

docs:update refreshes the root README TOC and then copies the root README to packages/cli/README.md, keeping the npm README for @vishot/cli in sync with the project overview.

Package-specific READMEs live next to their packages and are maintained independently.

Development

Install dependencies:

pnpm install

Run repository checks:

pnpm typecheck
pnpm test
pnpm lint

Use workspace filters for package-scoped work:

pnpm -F @vishot/core typecheck
pnpm -F @vishot/renderer-browser test:run
pnpm -F @vishot/mockup-desktop-vue story:dev

Build all packages:

pnpm build

Status

Vishot packages are early and may change while the capture protocol settles.

License

MIT