Manual screenshot system

Automated mobile manual screenshots¶

The end-user manual contains reproducible screenshots of the built Steady interface. A dedicated Playwright runner starts the browser build with a fixed mobile presentation, walks through selected views in German and English, and writes the generated PNG files directly into the published manual directories.

Purpose and evidence¶

The run verifies and documents together:

that the dedicated Vite manual build starts,
that central views and configuration dialogs can be reached in Chromium,
that German and English screenshots are produced with identical filenames,
that localized documentation annotations are generated,
that the image paths used by the end-user manual remain available,
and that the documentation checks still pass after generation.

Browser evidence, not Android evidence

The run shows the React interface in a mobile Chromium viewport. It does not prove a successful native Android build or correct behavior of SQLite, Android Keystore, device authentication, notifications, or native system dialogs.

Architecture¶

flowchart LR
  A[Manual dispatch or request counter] --> B[GitHub Actions]
  B --> C[npm ci]
  C --> D[isolated Playwright package and Chromium]
  D --> E[Vite build in manual mode]
  E --> F[synthetic IndexedDB data]
  F --> G[mobile EN and DE walkthroughs]
  G --> H[temporary callout layer]
  H --> I[28 PNG files]
  I --> J[docs:check]
  J --> K[stage screenshot directories only]
  K --> L[bot commit when changed]

Component	Responsibility
`npm run build:manual`	builds Vite in `manual` mode
`playwright.manual.config.js`	defines the browser, viewport, timeouts and local preview server
`src/main.jsx`	loads capture preparation only when the build switch is active
`src/manual-capture.js`	creates the isolated synthetic application state
`tests/manual/manual-walkthroughs.spec.js`	navigates through app and dialogs, adds callouts and writes the manual PNG files
`.github/workflows/manual-screenshots.yml`	runs the controlled process in GitHub Actions
`docs/manual-screenshots.request`	triggers a new CI run when its contents change

Double activation barrier¶

The capture state is activated only when both conditions are satisfied:

Vite was built in manual mode and therefore defines VITE_MANUAL_CAPTURE=1.
The requested URL additionally contains manualCapture=1.

A normal npm run build, npm run android:sync, or release pipeline sets the build switch to 0. A URL parameter alone therefore cannot activate the capture state. Conversely, a manual build without the explicit URL parameter does not create a demo session.

src/main.jsx dynamically loads src/manual-capture.js only when the build switch is active. The service worker is also not registered in capture mode, preventing an older cache from changing the documented state.

Synthetic data and privacy¶

Each Playwright test starts in a fresh browser context with its own browser database. Capture preparation:

uses only synthetic Recovery records from src/data/recovery-demo-data.js,
localizes free-form example text separately for German and English,
uses the neutral example name Alex,
marks the privacy notice, profile and product tour as completed,
clears Companion memories and important-note references,
uses no provider tokens, backups or imported user data,
and normalizes recovery examples to the general social-media and aimless-scrolling area.

Device locking and screenshot protection are disabled only inside this artificial browser session. Product defaults and native Android security are not changed.

Documentation annotations¶

Before each image, the test creates a temporary fixed overlay layer. It draws yellow frames around relevant controls and adds numbered labels in the documentation language.

The callout layer:

changes neither React state nor IndexedDB data,
uses pointer-events: none,
is inserted only immediately before the screenshot,
is removed directly after the PNG file is written,
and is never visible in normal builds or in the app.

The annotations are orientation aids, not pixel-perfect visual-regression references.

Browser emulation and documented walkthrough¶

Setting	Value
Viewport	`412 × 915` CSS pixels
Device scale factor	`1`
Input	mobile presentation with touch
Color scheme	dark mode
Motion	reduced animations
Time zone	`Europe/Berlin`
Fixed time	July 15, 2026 at 19:30
Parallelism	one worker, language runs executed sequentially

Fourteen views are generated for each language:

Today / daily check-in,
Journal,
Recovery,
Patterns and Life Wheel,
Explorer,
Toolbox,
edit mode,
section management,
section-to-Life-Wheel assignment,
basic field configuration,
field analytics and radar role,
Life Wheel axis management,
Recovery change areas,
counter and relapse configuration.

The tests use accessible roles and visible labels for navigation where possible. Toasts, carets and scrollbars are hidden for a calmer documentation presentation. Screenshots contain the current viewport rather than an artificially stitched full-page image.

Limitations¶

The following are not tested or are not represented faithfully:

native Android status and navigation bars,
SQLite and Keystore behavior,
biometric or system device authentication,
notification permissions,
file pickers, share sheets and other Android system surfaces,
manufacturer-specific font, scaling or WebView differences,
dialogs, settings and edge cases outside the defined walkthrough,
and pixel-perfect regression against an approved reference image.

A successful run means: The selected browser views could be built, opened, annotated and captured under the defined conditions. It does not replace Android instrumentation, complete functional testing or manual visual approval.

Local execution¶

npm ci
npm install --no-save --package-lock=false @playwright/test@1.55.0
npx playwright install chromium
npm run docs:screenshots
npm run docs:check

Playwright remains an isolated documentation dependency and is not permanently added to package.json or package-lock.json. npm run docs:screenshots builds the app in manual mode, starts vite preview locally on port 4173, and executes both language runs.

CI refresh¶

The workflow starts only through workflow_dispatch or when docs/manual-screenshots.request changes on main. Normal UI commits therefore do not automatically create new binary files.

The workflow uses Node.js 24, installs Playwright without changing the lockfile, installs Chromium, generates both image sets, and then runs npm run docs:check. Only after those steps does it prepare a commit.

git add docs-site/en/assets/manual docs-site/de/assets/manual

Other working-tree changes are not included in the screenshot commit. If the build, navigation, callout generation, screenshot generation or documentation validation fails, no commit is made and the last working images remain in place. Parallel runs share a concurrency group, and a newer run replaces an older run that is still executing.

Maintenance rules¶

After a visible change to a documented view:

Update the runner, selectors and callout targets for the new interface.
Check both language runs locally or increment the request counter.
Visually review all 28 generated images.
Confirm that the German and English directories contain the same fourteen filenames.
Never hand-retouch screenshots or replace them with images containing real data.

Renaming navigation or removing a target is allowed to make the run fail visibly. An obsolete walkthrough must not silently produce screenshots that merely appear current.

Sources and output paths¶

Purpose	Path
Capture configuration	`playwright.manual.config.js`
User walkthrough and callouts	`tests/manual/manual-walkthroughs.spec.js`
Isolated application state	`src/manual-capture.js`
Build separation	`vite.config.js`, `src/main.jsx`
CI process	`.github/workflows/manual-screenshots.yml`
Internal quick guide	`docs/MANUAL-SCREENSHOTS.md`
English images	`docs-site/en/assets/manual/`
German images	`docs-site/de/assets/manual/`