bggpipe/docs/bgg-upload-flow.md

# BGG "Add to Collection" flow — recon notes for the upload stage

Recorded 2026-08-01 by walking the flow manually on boardgamegeek.com (Wingspan,
id 266192) while logged in. Dialog opened, inspected, and **cancelled without
saving**. These notes are the selector documentation the spec requires before
automating Stage 5.

## Entry point

- Game page has **two** "Add To" buttons (one in the game header module, one
  lower on the page) — target the first, but match by accessible name, not
  position. Button's accessible name is "Add To" with adjacent text
  "Collection".
- Clicking opens a `role="dialog"` containing a `<form>`. Dialog heading shows
  a "Loading..." span before content settles — **wait for the game-name
  heading** (e.g. `getByRole('heading', {name: gameName})`) before
  interacting.

## Main dialog structure

- **Status checkboxes**, each wrapped in a `<label>`: Own, Prev. Owned,
  For Trade, Want to Play, Want in Trade, Want to Buy, Pre-ordered, Wishlist.
  → `dialog.getByLabel('Own')` and check it. Nothing is pre-checked.
- Rating: a 1–10 slider plus a "Rating" text input. We do not set ratings.
- Comment (public) textbox — unused by us.
- "Advanced (private info, parts exchange)" expander: Price Paid, Current
  Price, Quantity, Acquisition Date, Acquired From, Inventory Date/Location,
  Private Comment, Want/Has Parts. All unused (we don't track provenance).
- "Customize Item Info (title, image)" expander: Custom Title, Custom Image
  Id, plus **manual version-override fields** (Publisher Id, Language select,
  Year, Other, Barcode). These are for defining a custom version — do NOT use
  them; always pick a cataloged version instead (or none).
- Footer: `Save` (`type="submit"`) and `Cancel` buttons.

## Version picker ("Set version/edition")

- Button labeled **"Set version/edition"** near the top of the dialog swaps
  the dialog content to a "Versions" sub-view (same `role="dialog"`).
- The sub-view is a **paginated list with NO search/filter box**. Each
  listitem's text is the full canonical version name + year, e.g.
  "Flügelschlag (German fifth edition) (2024)" — these names match the
  version names returned by `/thing?id=X&versions=1`.
- Selection strategy: resolve the target version NAME from the XML API,
  then page through the list matching listitem text
  (`getByRole('listitem').filter({hasText: versionName})`). Newest years
  appear first.
- The sub-view has its own **Cancel** that returns to the main dialog — it
  is a different button from the main dialog's Cancel. Two-level dismissal.

## Automation gotchas observed

1. **Element references go stale constantly.** The page re-renders after
   load and after every dialog transition; clicks on cached handles silently
   miss. Playwright's auto-waiting role/label locators handle this — never
   cache element handles across a dialog state change.
2. **Dialog persists in the DOM after cancel**, just hidden
   (`offsetParent === null`). "Is the dialog gone" checks must test
   visibility, not existence. Same applies when verifying a save completed.
3. First click on "Add To" right after page load can no-op (hydration race).
   Wait for network-idle or the button's stable state before clicking.
4. Verify saves via the collection API (`--verify`), not by UI state.

## Playwright locator sketch

```python
page.get_by_role("button", name="Add To").first.click()
dialog = page.get_by_role("dialog")
dialog.get_by_role("heading", name=game_name).wait_for()
dialog.get_by_label("Own").check()
if version_name:
    dialog.get_by_role("button", name="Set version/edition").click()
    # page through listitems until version_name matches, then click it
dialog.get_by_role("button", name="Save").click()
```

Unverified so far (needs a real, sacrificial save on one game before batch
runs): pagination controls in the version sub-view, exact post-save behavior
(toast? dialog close? redirect?), and how the dialog differs when the game is
ALREADY in the collection (second-copy flow must create a new entry, not edit
the existing one).

## Login page (recon 2026-08-01, anonymous probe via Playwright)

- **Cloudflare Turnstile blocks headless browsers outright**: the headless
  shell never gets past "Just a moment..." (`cf-turnstile-response` hidden
  input, no form). A normal **headed** Chromium passed the check without
  interaction. Hence `bggpipe upload` runs headed by default; `--headless`
  exists but expect login to fail there. A first login in headed mode may
  still need one human click on the challenge widget; the session then
  persists via `storage_state.json` (gitignored).
- **BGG pages never reach Playwright's `networkidle`** — ad/analytics
  requests poll forever. Navigate with `wait_until="domcontentloaded"` and
  rely on element-level auto-waiting.
- Verified form selectors at `/login`: `#inputUsername` (name=`username`,
  formcontrolname=`username`), `#inputPassword`, and a button with
  accessible name **"Sign In"** (`type="button"` — Angular handles submit,
  so click the button rather than pressing Enter and hoping for a form
  submit). Labels "Username"/"Password" point at those ids. Cookie-consent
  checkboxes (Essential, Performance Analytics, ...) render on the same
  page but did not overlay the form in the probe.
- Logged-in detection heuristic (unverified): the header shows a "Sign In"
  link only when logged out.