FlowPilot/docs/superpowers/specs/2026-04-05-multi-page-automation-extension-design.md

Multi-Page Automation Chrome Extension - Design Spec

Overview

A Chrome extension that automates a multi-step OAuth account registration and verification workflow. The extension operates across multiple websites (VPS panel, OpenAI auth, QQ Mail, ChatGPT) using a Side Panel as the control center and Content Scripts for DOM manipulation.

User Story

The user needs to repeatedly perform a multi-step workflow involving:

1. Getting an OAuth link from a VPS panel
2. Registering a new account on the linked auth page (multi-page: email/password → verify code → name/birthday)
3. Receiving email verification codes (twice: registration + login)
4. Logging into ChatGPT with the new account
5. Completing OAuth callback verification

The extension automates DOM interactions at each step, with the user triggering steps manually via the Side Panel (semi-automatic mode, with future upgrade to full automation).

Architecture

┌─────────────────────────────────────────────────┐
│                  Chrome Extension                │
├──────────┬──────────────┬───────────────────────┤
│ Side Panel │  Background  │    Content Scripts     │
│ (Control)  │  (Service    │  (Injected per site)   │
│            │   Worker)    │                        │
│ - Step list│ - Tab mgmt   │ - vps-panel.js         │
│ - Buttons  │ - Msg relay  │ - signup-page.js       │
│ - Status   │ - State store│ - qq-mail.js           │
│ - Logs     │ - Orchestrate│ - chatgpt.js           │
│ - Reset    │   tab switch │ - utils.js (shared)    │
└──────────┴──────────────┴───────────────────────┘

Components

• Side Panel: Persistent right-side panel showing all steps with action buttons, status indicators, shared data display (OAuth URL, email, etc.), debug log area, and a reset button. On open/reload, restores full state from chrome.storage.session.
• Background Service Worker: Central dispatcher and orchestrator. Manages tab creation/switching, stores flow state in chrome.storage.session (NOT in-memory, as MV3 service workers can be terminated after 30s of inactivity), relays and routes messages between Side Panel and Content Scripts, and handles tab-switching choreography between steps.
• Content Scripts: Per-domain scripts injected into target pages, each responsible for DOM operations (reading, filling forms, clicking buttons). All share utils.js for common utilities.

Communication — Unified Message Protocol

All messages between components use a standard format:

{
  type: "ACTION_NAME",    // e.g. "FILL_SIGNUP", "CODE_FOUND", "STEP_COMPLETE", "STEP_ERROR", "LOG"
  source: "qq-mail",      // sender identifier
  target: "signup-page",  // intended receiver (optional, Background uses for routing)
  step: 4,                // which workflow step this relates to
  payload: { ... },       // data
  error: null             // error message string (if any)
}

Message routing:

• Side Panel <-> Background: chrome.runtime.sendMessage
• Background -> Content Script: chrome.tabs.sendMessage (only after content script reports ready)
• Content Script -> Background: chrome.runtime.sendMessage
• Background is the central router: it receives all messages and forwards to the correct target based on target field and tabRegistry.

Content Script Readiness Protocol

Background must NOT send messages to a content script immediately after opening/navigating a tab. Instead:

1. Content script sends { type: "CONTENT_SCRIPT_READY", source: "vps-panel" } message on load
2. Background registers the tab as ready in the tabRegistry
3. Only then does Background send action commands to that tab
4. If Background needs to send a command but the script isn't ready yet, it queues the command and sends it when the ready signal arrives (with a 15s timeout → error)

Tab Registry

Background maintains a tabRegistry in chrome.storage.session:

{
  "vps-panel": { "tabId": 123, "ready": true },
  "signup": { "tabId": 124, "ready": true },
  "qq-mail": { "tabId": 125, "ready": false },
  "chatgpt": { "tabId": 126, "ready": true }
}

Before operating on a tab, Background checks if the tab still exists via chrome.tabs.get(). If the tab was closed, it reopens and waits for the ready signal.

Tab Switching Orchestration

When a step requires cross-tab coordination (e.g., step 4: get code from QQ Mail → fill into signup page), the orchestration is always handled by Background:

1. Content script A (e.g., qq-mail.js) sends result to Background: { type: "CODE_FOUND", payload: { code: "123456" } }
2. Background stores the data in chrome.storage.session
3. Background activates target tab via chrome.tabs.update(tabId, { active: true })
4. Background sends command to Content script B: { type: "FILL_CODE", payload: { code: "123456" } }
5. Content script B executes and reports STEP_COMPLETE or STEP_ERROR

Content scripts NEVER communicate directly with each other.

Workflow Steps

Step	Button	Executor	Action
1	Get OAuth Link	vps-panel.js	Check VPS login state → Click OAuth login → Click Codex login → Read auth URL → Send to Background
2	Open Signup & Click Register	Background + signup-page.js	Background opens auth URL in new tab → signup-page.js loads and clicks "Register" button
3	Fill Email & Password	signup-page.js	Read email from Side Panel input (via Background) → Fill email + password (mimashisha0.0) → Submit
4	Get Signup Verification Code	qq-mail.js → Background → signup-page.js	Background opens QQ Mail tab → qq-mail.js polls for new email from OpenAI → Extracts code → Background switches to signup tab → signup-page.js fills code and confirms
5	Fill Name & Birthday	signup-page.js	After code verification, page transitions to profile form → Fill random English name + random birthday (age 19-25) → Click complete registration
6	Login ChatGPT	Background + chatgpt.js	Background opens chatgpt.com in new tab → chatgpt.js clicks login → Enters email → If password field appears, fills password; otherwise waits for OTP flow → Submit
7	Get Login Verification Code	qq-mail.js → Background → chatgpt.js	Background switches to QQ Mail tab → qq-mail.js polls for email newer than step 4's → Extracts code → Background switches to ChatGPT tab → chatgpt.js fills code → Login complete
8	Complete OAuth	Background (webNavigation) + chatgpt.js	chatgpt.js navigates to step 1's oauthUrl → Background captures localhost redirect via webNavigation listener → Stores localhostUrl
9	VPS Verify	vps-panel.js	Background switches to VPS panel tab → vps-panel.js pastes localhostUrl into input → Clicks verify button

Content Script URL Matching

Script	Match Patterns	all_frames
utils.js	(included by all below)	—
vps-panel.js	http://154.26.182.181:8317/*	false
signup-page.js	https://auth0.openai.com/*, https://auth.openai.com/*, https://accounts.openai.com/*	false
qq-mail.js	https://mail.qq.com/*, https://wx.mail.qq.com/*	true
chatgpt.js	https://chatgpt.com/*	false

Note: qq-mail.js uses all_frames: true because old QQ Mail (mail.qq.com) renders inbox inside iframes.

Content Script Details

utils.js (shared)

Loaded before every content script. Provides:

// Wait for a DOM element to appear, with timeout
async function waitForElement(selector, timeout = 10000)

// React-compatible form filling — triggers proper event chain
function fillInput(el, value) {
  const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
    window.HTMLInputElement.prototype, 'value'
  ).set;
  nativeInputValueSetter.call(el, value);
  el.dispatchEvent(new Event('input', { bubbles: true }));
  el.dispatchEvent(new Event('change', { bubbles: true }));
}

// Send log message to Side Panel (via Background)
function log(message, level = 'info')

// Send step result to Background
function reportComplete(step, data = {})
function reportError(step, errorMessage)

// Standard ready signal
function reportReady(source)

vps-panel.js

• Step 1: Check login state (look for known logged-in DOM indicator); if not logged in → reportError(1, "VPS panel not logged in, please log in first"). Then: locate OAuth login button → click → wait for Codex login button to appear → click → wait for auth URL to appear in DOM → read it → reportComplete(1, { oauthUrl })
• Step 9: waitForElement for URL input field → fillInput with localhostUrl → click verify button → reportComplete(9)

signup-page.js

• Step 2: On ready, detect if current page has a "Register" / "Sign up" button → click it → reportComplete(2)
• Step 3: waitForElement for email input → fillInput email → fillInput password (mimashisha0.0) → click submit → reportComplete(3)
• Step 4 (receiving end): waitForElement for verification code input → fillInput code → click confirm → reportComplete(4)
• Step 5: waitForElement for name/birthday fields (page transition after code verification) → fillInput random first name, last name → fillInput random birthday → click complete → reportComplete(5)
• All DOM operations use waitForElement before acting
• All input filling uses fillInput (React-compatible)

qq-mail.js

• Check login state first; if not logged in → reportError(step, "QQ Mail not logged in, please log in first")
• QQ Mail version handling:
  • Old version (mail.qq.com): Content is inside iframes. With all_frames: true, the script runs in each frame. Only the frame containing the inbox list should act.
  • New version (wx.mail.qq.com): SPA, no iframes. All content in main frame with dynamic DOM updates.
• Polling strategy (no page refresh):
  • Click inbox refresh button (or equivalent DOM trigger) every 3 seconds
  • Observe email list DOM for new entries matching sender filter (e.g., openai, noreply) or subject filter (e.g., verify, verification, code)
  • Extract verification code from email preview/snippet if visible, or click into email and extract from body
  • Log each poll attempt: log("Polling QQ Mail... attempt 3/20")
• Step 4: Find email newer than flow start time → extract 6-digit code via regex → reportComplete(4, { code, emailTimestamp })
• Step 7: Find email newer than step 4's emailTimestamp → extract 6-digit code → reportComplete(7, { code })
• Timeout after 60 seconds (20 attempts) → reportError(step, "No matching email found after 60s")

chatgpt.js

• Step 6: waitForElement for login button → click → waitForElement for email input → fillInput email → submit → detect next state:
  • If password field appears → fillInput password → submit → reportComplete(6)
  • If no password field (OTP flow) → reportComplete(6, { needsOTP: true }) (code will come from step 7)
• Step 7 (receiving end): waitForElement for code input → fillInput code → submit → reportComplete(7)
• Step 8: Navigate to oauthUrl (from storage) → page will redirect → log("Navigating to OAuth URL, waiting for redirect...") → (localhost capture handled by Background)

Data Flow

Data persisted in chrome.storage.session (survives service worker termination), passed between steps:

Step 1  → oauthUrl          (authorization link)
Step 3  → email, password   (from Side Panel input + hardcoded)
Step 4  → lastEmailTimestamp (to distinguish step 7's email)
Step 8  → localhostUrl      (OAuth callback URL)

Additionally stored:

• currentStep: which step is active (for UI restore)
• stepStatuses: { 1: "completed", 2: "completed", 3: "running", ... } (for UI restore)
• tabRegistry: tab ID mapping (for tab management)
• logs: array of log entries (for UI restore)
• flowStartTime: timestamp when flow began (for email filtering)

Random Data Generation (in Background)

• English names: Built-in list of common first names + last names, randomly combined
• Birthday: Current year minus 19-25 years, random month/day, formatted per the target form's expected format

Side Panel UI

┌──────────────────────────────────┐
│  Multi-Page Automation    [Reset]│
├──────────────────────────────────┤
│  OAuth URL: [显示/未获取]         │
│  Email:  [________粘贴邮箱______] │
│  Status: Step 3 running...       │
├──────────────────────────────────┤
│  1  [Get OAuth Link]      ✅     │
│  2  [Open Signup]         ✅     │
│  3  [Fill Email/Password] ⏳     │
│  4  [Get Signup Code]     ⬚ 禁用 │
│  5  [Fill Name/Birthday]  ⬚ 禁用 │
│  6  [Login ChatGPT]       ⬚ 禁用 │
│  7  [Get Login Code]      ⬚ 禁用 │
│  8  [Complete OAuth]      ⬚ 禁用 │
│  9  [VPS Verify]          ⬚ 禁用 │
├──────────────────────────────────┤
│  Log:                            │
│  10:23:01 [INFO] Step 1 started  │
│  10:23:03 [INFO] Found OAuth btn │
│  10:23:05 [OK]   Step 1 done     │
│  10:23:05 [INFO] oauthUrl saved  │
│  10:23:08 [INFO] Step 2 started  │
│  10:23:10 [INFO] Tab opened      │
│  10:23:12 [OK]   Register clicked│
│  10:23:15 [ERR]  Step 3 failed:  │
│           email input not found  │
│  10:23:15 [INFO] Retry step 3... │
└──────────────────────────────────┘

UI behaviors:

• Step interlock: When a step is running, all other buttons are disabled. Next step button stays disabled until previous step succeeds. Failed steps show ❌ and can be retried. Completed steps show ✅ and can be re-run.
• State restore: On Side Panel open/reload, read currentStep, stepStatuses, logs, and all data fields from chrome.storage.session and render.
• Reset button: Clears all chrome.storage.session data, resets all steps to pending, clears logs. Does NOT close open tabs (user may want them).
• Email input: Editable text field. User pastes DuckDuckGo-generated email here before step 3.
• Log area: Scrollable, auto-scrolls to bottom. Shows timestamp, level (INFO/OK/WARN/ERR), and message. Each content script action logs what it's about to do and the result.

Debugging & Observability

Every step must be fully debuggable. The user should never be stuck wondering "what went wrong".

Log Everything

Each content script logs at these checkpoints:

1. Step start: "Step N started"
2. Waiting for element: "Waiting for selector: #email-input..."
3. Element found/not found: "Found #email-input" or "Timeout waiting for #email-input after 10s"
4. Action taken: "Filled email input with xxx@duck.com", "Clicked submit button"
5. Page transition: "Page URL changed to https://..."
6. Polling progress: "Polling QQ Mail... attempt 5/20, no match yet"
7. Data extracted: "Verification code found: 123456"
8. Step result: "Step N completed successfully" or "Step N failed: [reason]"

Error Recovery Guide

When a step fails, the error message should include actionable guidance:

Error	Guidance shown in log
VPS not logged in	"Please log in to VPS panel at http://154.26.182.181:8317 and retry"
QQ Mail not logged in	"Please log in to QQ Mail and retry"
Element not found (timeout)	"Could not find [selector] on [url]. Page may have changed layout. Check DevTools."
Email not received (timeout)	"No matching email after 60s. Check QQ Mail manually. Email may be in spam."
Tab was closed	"Tab [name] was closed. Will reopen on retry."
Content script not ready	"Content script on [url] did not respond in 15s. Try refreshing the tab and retry."
Unknown error	"Unexpected error: [message]. Check DevTools console on [tab name] for details."

DevTools Integration

• Each content script logs to the browser console with a prefix: [MultiPage:vps-panel], [MultiPage:qq-mail], etc.
• Background service worker also logs with [MultiPage:bg] prefix.
• All chrome.storage writes are logged: [MultiPage:bg] storage.set: stepStatuses = {...}
• This allows using Chrome DevTools on any tab or the service worker to see detailed execution trace.

Robustness

Login State Detection

• VPS panel (step 1): Check for known logged-in DOM indicator before operating; if absent, reportError with guidance and pause.
• QQ Mail (steps 4, 7): Check for inbox DOM indicator; if absent, reportError with guidance and pause.

DOM Element Waiting

All content script DOM operations use waitForElement(selector, timeout) from utils.js. Default timeout: 10 seconds. On timeout, reportError with the selector and URL for debugging.

Email Polling

• Poll QQ Mail inbox every 3 seconds for matching email (filter by sender/subject keywords)
• Step 7 only accepts emails newer than step 4's lastEmailTimestamp to avoid duplicates
• Each poll attempt is logged with attempt count
• Timeout after 60 seconds (20 attempts); reportError with guidance to check spam folder

Localhost Redirect Capture

• chrome.webNavigation.onBeforeNavigate listener is registered in Background only when step 8 starts
• Listener matches URL starting with http://localhost
• On capture: store localhostUrl, remove listener, reportComplete(8)
• If not captured within 30 seconds: reportError with guidance
• Listener is always removed when step 8 ends (success or failure)

Page Transitions

• After form submissions, signup-page.js and chatgpt.js must handle page navigation/SPA route changes
• Use waitForElement on the NEXT expected element after submission, not just submit and hope
• If URL changes (full navigation), the content script re-injects and sends a new READY signal; Background re-sends the pending command

Permissions (manifest.json)

{
  "permissions": [
    "sidePanel",
    "tabs",
    "webNavigation",
    "storage",
    "scripting",
    "activeTab"
  ],
  "host_permissions": [
    "http://154.26.182.181:8317/*",
    "https://auth0.openai.com/*",
    "https://auth.openai.com/*",
    "https://accounts.openai.com/*",
    "https://mail.qq.com/*",
    "https://wx.mail.qq.com/*",
    "https://chatgpt.com/*",
    "http://localhost/*"
  ]
}

Note: scripting permission enables chrome.scripting.executeScript for dynamic injection when the auth flow redirects to unexpected domains.

Technical Decisions

• Manifest V3: Required for current Chrome extension development
• Side Panel API: chrome.sidePanel for persistent control panel
• Pure Content Script approach: No external dependencies, direct DOM manipulation
• State in chrome.storage.session: MV3 service workers can terminate after 30s idle; all flow state must be persisted, not held in memory
• React-compatible form filling: Use native setter + event dispatch pattern for all React-based target pages
• Content script readiness protocol: Scripts report ready before receiving commands; commands queued if not ready
• Unified message protocol: All inter-component messages use same format with type/source/target/step/payload/error
• Shared utils.js: Common utilities loaded by all content scripts to avoid duplication
• Background as sole orchestrator: All cross-tab coordination goes through Background; content scripts never talk to each other
• webNavigation listener scoped to step 8: Registered on step start, removed on step end, avoids false triggers
• Semi-automatic first: Each step triggered manually, upgrade to full automation later
• DuckDuckGo email generation: Manual step (user clicks DuckDuckGo panel), user pastes email into Side Panel input

Future Enhancements

• Full automation mode (single button to run all steps)
• DuckDuckGo API integration for automatic email generation
• Batch execution support
• Error recovery and auto-retry logic
• Export logs for troubleshooting