Flow Batch

A local-only Chrome (Manifest V3) side-panel extension for internal use that batch-runs a list of prompts through Google Flow (labs.google/fx/tools/flow), then auto-downloads and organizes the generated images/videos.

No accounts, no server, no limits — everything runs client-side in the browser.

• Spec: docs/superpowers/specs/2026-06-11-flow-batch-extension-design.md
• Plan: docs/superpowers/plans/2026-06-11-flow-batch-extension.md

Architecture

Side Panel (React)  →  Background worker (BatchEngine state machine)  →  Content script (FlowPageAdapter)
                                   │                                              │ drives
                                   ▼                                              ▼
                            chrome.downloads  ◀── result URLs ── MAIN-world network listener ── Google Flow

All decision/queue logic lives in src/core behind injected ports and is unit-tested (46 tests). Every Google-Flow-specific DOM selector lives in one file: src/content/flow-page-adapter.ts (SELECTORS block).

Develop

npm install
npm run dev      # WXT dev server with HMR
npm test         # Vitest unit tests
npm run build    # production build → .output/chrome-mv3/

harness/ is a mock Flow page (decoy editables, pre-existing gallery, composer emulating both input-syncing and strict revert-style editors) for testing FlowPageAdapter in a real Chrome without a Google session: npx vite harness --port 5610, then drive window.FlowHarness from DevTools.

Install (load unpacked)

1. npm run build
2. Open chrome://extensions, enable Developer mode.
3. Load unpacked → select .output/chrome-mv3/.
4. Open labs.google/fx/tools/flow, click the extension icon to open the side panel.

⚠️ Before first real use: tune the Flow selectors (manual)

The DOM selectors and applySettings setters in src/content/flow-page-adapter.ts are best-effort placeholders that must be verified against the live Flow UI. With Flow open and DevTools on the page:

1. Inspect the prompt box, send button, reference file input, and result tiles; update the SELECTORS constant to match.
2. Implement the applySettings setters (model / mode / aspect ratio / images-per-prompt) against Flow's live menus.
3. Verify result-URL capture (review note M1): the MAIN-world listener (entrypoints/flow-net.content.ts) assumes result media URLs appear in the fetch/XHR request URL and match \.(png|jpe?g|webp|mp4|webm). If Flow instead returns result URLs inside a JSON response body, feed ResultBus from the response, or fall back to scraping SELECTORS.resultMedia from the results container inside FlowPageAdapter.waitForResults.
4. Verify the expected-count (review note M4): waitForResults waits for imagesPerPrompt URLs. Confirm Flow actually emits that many separate media URLs per submit (e.g. "x4" might render one grid image → set expected accordingly, or it will hang until timeout).

Manual E2E checklist

• Side panel opens on the Flow tab.
• 3-prompt smoke batch: paste 3 prompts, folder flow-batch-test, auto-download images on, Run → 3 files land in Downloads/flow-batch-test/ as 001.png, 002.png, 003.png; progress ends in done.
• Pause mid-run → status paused; Resume → finishes remaining prompts.
• Start a batch, close the side panel mid-run, reopen → progress reflects persisted state (the run keeps going in the background).

Known follow-ups (from final code review)

• I2 (Stop latency): Stop is observed at item boundaries, so a click during a long waitForResults (up to the 120s item timeout) or the inter-item delay isn't acted on immediately. Make waitForResults abortable if prompt Stop matters.
• v2 (deferred by design): Queue / Gallery / Library / Logs tabs; wiring the per-prompt "different-for-each" reference picker into the UI (the engine already supports it and it's unit-tested — the UI currently ships "same-for-all").