Metadata-Version: 2.4
Name: shots
Version: 0.2.0
Summary: LLM-assisted high-res marketing screenshots for SaaS apps (generic login via Playwright storage_state).
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright>=1.40.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pillow>=10.0.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == 'llm'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.0; extra == 'yaml'
Description-Content-Type: text/markdown

# shots

Generic, open-source friendly tooling to capture high-res marketing screenshots of a SaaS app.

**Key idea**: you log in once manually; `shots` saves a Playwright `storage_state.json`. After that, it can run repeatedly headless, optionally guided by an LLM (vision) to navigate and/or crop.

## Install

```bash
python -m venv .venv
source .venv/bin/activate

pip install -e ".[llm,yaml]"
playwright install chromium
```

## Setup

```bash
cp shots.yaml.example shots.yaml   # edit with your app's URL and shots
cp .env.example .env                # add your OPENAI_API_KEY
```

Both `shots.yaml` and `.env` are gitignored.

## 1) One-time manual login

```bash
shots login --base-url https://your-app.example.com --out-dir shots_out
```

This writes `shots_out/storage_state.json`.

## 2) Run required screenshots from a config

```bash
export OPENAI_API_KEY=...
shots run-config --config shots.yaml --out-dir shots_out --use-llm --use-llm-crop --save-source
```

## Config format (YAML)

```yaml
base_url: https://your-app.example.com
start: /app

defaults:
  viewport_preset: desktop
  full_page: true
  max_nav_steps: 12

shots:
  - id: dashboard-hero
    description: >
      Capture the main dashboard with KPI cards and a chart visible.
      Navigate via the left nav if needed. Close any modal/tour/cookie overlay.
    url: /app/dashboard

  - id: integrations
    description: >
      Show Settings -> Integrations page listing available integrations.
    viewport_preset: laptop
```

## Notes

* `--use-llm` enables multi-step "acquire the shot" behavior: the model returns one action at a time until it says `done`.
* `--use-llm-crop` asks the model to choose a crop rectangle for a marketing-friendly framing.
* All navigation is kept **same-origin** as `base_url`.
