document360-capture

CLI that captures product screenshots from Playwright specs. Login once, capture many. Companion to document360-writer.

Why

Doc-screenshot pipelines hit two walls in practice:

1. MFA + per-run login. Spinning up Chromium for every capture and asking the human to log in each time burns time and rules out repeatable runs.
2. Annotation by hand. Adding numbered callouts, highlights, and redactions in an image editor is the slowest part of doc maintenance.

This CLI solves both. d360-capture auth opens Chromium once, the human logs in (MFA at their own pace), and a Playwright storageState is saved; every capture after that reuses the session. Specs declare what to highlight, annotate and redact, and the CLI draws it.

Two stages

Taking the picture and drawing on it are separate commands:

| Stage | Command | What it does | |---|---|---| | capture | d360-capture capture | Drives the browser. Writes the raw PNG and resolves every declared selector into image-space boxes (<id>.annotations.json). | | annotate | d360-capture annotate | Draws the markers onto the raw. No browser, no login — a fraction of a second per picture. |

capture runs both by default. The split matters when you want to change how a picture looks — reword a callout, retune the marker style — because that is a re-draw, not a re-shoot.

The measurement stays inside capture on purpose: a cropped screenshot's coordinate origin is only knowable at the instant the shutter fires, so the boxes are resolved there and recorded for annotate to read.

Install

npm install -g document360-capture

Postinstall downloads the Chromium binary via npx playwright install chromium.

Quick start

cd <your-repo>
d360-capture init                      # one-time per project — writes .d360-writer/capture.json
d360-capture auth --profile staging     # one-time per machine — log in, press Enter when done
d360-capture capture                    # run every spec in captureDir
d360-capture capture <spec-id>          # run one spec
d360-capture annotate --all             # re-draw without re-shooting

Commands

| Command | Description | |---|---| | d360-capture init | Interactive setup. Writes .d360-writer/capture.json. | | d360-capture auth [--profile <name>] | Open Chromium; log in at your own pace; press Enter to save the session. | | d360-capture capture [<spec-id>] [--profile <name>] [--no-annotate] [--allow-mutations] | Run one spec or all of them, then draw the markers. --no-annotate stops after the raw. | | d360-capture annotate [<spec-id>] [--all] [--force] | Draw the markers on shots already taken. Name one shot or pass --all. | | d360-capture list | Specs, when each was last captured, and when each was last drawn. | | d360-capture doctor [--profile <name>] | Validate config, auth-state, browser, and capture dir. | | d360-capture status | Print resolved config (secrets redacted). | | d360-capture profile [list\|use <name>\|show [name]] | Manage the connection profiles for this repo. |

A bulk capture never runs a spec that writes to your app. Specs classified as mutating are excluded and listed; run those one at a time by name.

Spec helpers

A spec declares its capture region and its markers, then makes one call:

// CAPTURE-SAFETY: readonly
import { test } from '@playwright/test';
import { gotoResilient, waitPastLogin, captureShot, type Placeholder } from 'document360-capture/helpers';

const PLACEHOLDER: Placeholder = {
  id: 'add-item-dialog',
  saveTo: '.d360-writer/user-docs/_screenshots/add-item-dialog.raw.png',
  // The region to crop to. Declared, never screenshotted by hand — see the warning below.
  clipTo: '[role="dialog"]',
  highlight: ['<selector of the control to draw attention to>'],
  annotations: [{ target: '<selector>', label: '1', text: 'Short explanation for the legend' }],
  redact: ['<selector matching every sensitive cell>'],
};

test(PLACEHOLDER.id, async ({ page }) => {
  await gotoResilient(page);
  await waitPastLogin(page, new RegExp(process.env.CAPTURE_AUTH_BOUNDARY!));

  await page.click('[aria-label="Open settings"]');
  await page.click('button:has-text("+ Add")');
  await page.locator('[role="dialog"]').waitFor({ state: 'visible' });

  await captureShot(page, PLACEHOLDER);   // takes the screenshot AND resolves the boxes
});

Declare the region; never take the screenshot yourself. boundingBox() reports page coordinates while a cropped PNG's origin is the crop's top-left. A spec that calls .screenshot() on a locator and then resolves annotations separately produces boxes offset by the crop origin, so every callout lands in the wrong place and nothing errors. Set clipTo (or fullPage) and let captureShot own both halves.

Other helpers: captureScope() / scopeValue() read the prepared demo context injected as CAPTURE_SCOPE, and waitForIdle() / observeBusy() settle the page when you need it quiet before the next interaction (captureShot already waits before the shutter).

Each redact and highlight selector marks every element it matches, so one selector covers every row of a table. Annotations are first-match, because a numbered pin marks one thing.

Marker style

Optional. House style goes in the project config, and any spec can override it for one shot:

// .d360-writer/capture.json
{
  "annotation": {
    "enabled": true,
    "style": {
      "pin": { "fill": "#0969da", "radius": 14 },
      "highlight": { "stroke": "#0969da", "fill": "rgba(9,105,218,0.14)" },
      "legend": { "fontSize": 15 }
    }
  }
}

const PLACEHOLDER: Placeholder = { /* … */ style: { pin: { fill: '#8250df' } } };

The spec's declaration wins per field, so overriding a pin colour keeps the rest of the house style. Editing the config re-draws every picture on the next annotate --all. One rule is not negotiable: a redaction is always opaque, so a translucent redact.fill is ignored.

Output layout

<outputDir>/
  <id>.annotations.json      # what was measured: boxes, labels, capture facts
  raw/<id>.raw.png           # what the browser captured
  annotated/<id>.png         # what annotate drew — this is the one that publishes

The raw is kept, which is what makes a re-draw possible without a browser.

Config files

• <repo>/.d360-writer/capture.json (committed): paths, viewport, connection profiles (startUrl + authBoundaryUrlPattern per profile), annotation toggle and style.
• ~/.document360-capture/auth-states/<projectId>/<profile>.json (per-machine, never commit): Playwright storageState.

License

Proprietary — © 2026 Kovai.co. All rights reserved. See LICENSE.