take-doc-screenshots

name	take-doc-screenshots
description	Take screenshots of the running pgconsole app for documentation. Use when updating docs with screenshots or adding images to .mdx files.
disable-model-invocation	false
argument-hint	["page-or-feature"]

Take Documentation Screenshots

Capture screenshots of the running pgconsole app at http://localhost:5173 for use in documentation.

Prerequisites

• The dev server must be running (pnpm dev)
• shot-scraper must be installed (pipx install shot-scraper && shot-scraper install)
• cwebp must be installed (brew install webp)

Authentication

Login credentials are in pgconsole.toml under [[users]]. Use the first user entry.

1. Read pgconsole.toml to find the email and password from the first [[users]] entry
2. Call the login API to get a session token:

   curl -s -c cookies.txt -X POST http://localhost:5173/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"email":"<email>","password":"<password>"}'
   

3. Extract the pgconsole_token cookie value from cookies.txt
4. Create a Playwright auth state JSON file:

   {
     "cookies": [{
       "name": "pgconsole_token",
       "value": "<token>",
       "domain": "localhost",
       "path": "/",
       "httpOnly": true,
       "secure": false,
       "sameSite": "Lax"
     }],
     "origins": []
   }
   

Taking Screenshots

Write a Playwright script (.mjs file in the scratchpad directory) that:

1. Launches Chromium with viewport: { width: 1440, height: 900 } (no deviceScaleFactor — use 1x)
2. Sets the auth cookie via context.addCookies()
3. Navigates to http://localhost:5173
4. Uses Playwright actions (click, type, keyboard) to navigate to the desired state
5. Saves screenshots as PNG

CodeMirror Interaction

The SQL editor uses CodeMirror 6. To type into it:

• Click .cm-content to focus
• Use page.keyboard.type('SQL here', { delay: 5 }) to type
• Use page.keyboard.press('Control+Space') for autocomplete
• Use page.keyboard.press('Meta+a') to select all before replacing content
• Do NOT try to access cmView from the DOM — it's not exposed

UI Navigation

Key buttons to interact with:

• button with text SQL — opens a new query tab
• button with text Run — executes the query
• button with text Format — opens format dropdown
• button with text Quick SQL — opens quick SQL dropdown
• button with text Processes — opens processes modal
• Right-click on .cm-content for context menu

Dismissing Overlays

After capturing dropdown/modal screenshots, always dismiss with:

await page.keyboard.press('Escape');
await page.waitForTimeout(500);

An open overlay blocks clicks on other elements.

Image Processing

1. Convert PNGs to WebP: cwebp -q 90 input.png -o output.webp
2. Store in docs/images/features/<feature-name>/ (matching docs/features/<feature-name>.mdx)
3. Reference in MDX as ![Alt text](/images/features/<feature-name>/<image>.webp)
4. Clean up temporary PNG files after conversion

Image Convention

• Format: WebP (.webp), quality 90
• Dimensions: 1440x900 (1x resolution)
• Location: docs/images/ mirroring the docs/ structure
• Naming: <feature>-<description>.webp (e.g., sql-editor-autocomplete.webp)
• Alt text: brief description of what the screenshot shows