---
id: "223ffbd6-9746-4c15-99eb-435b6c0c6620"
name: "smartbook_complete()"
micro_summary: "Call when you need to auto-solve McGraw Hill Connect reading pages + fill-in-the-blank questions. Injects JSON.parse interceptor, loops through questions, fills answers, clicks confidence, clicks next."
status: "in_progress"
see_also: []
scope: "connect_auto() helper in agent_helpers.py + smartbook.js script in agent-workspace. Orchestrates the refresh→inject→wait→auto() dance for McGraw Hill Connect reading pages + fill-in-the-blank questions."
warnings: "Do not rely on stale `/tmp/smartbook.js` as the source of truth. The tracked repo script is preferred; `/tmp` is fallback only."
---
## `smartbook_complete(url=None, max_questions=999)`

One call auto-solves McGraw Hill Connect reading pages + fill-in-the-blank.

### Usage

```python
result = smartbook_complete()  # refresh current page, auto-solve
# or
result = smartbook_complete("https://ezto.mheducation.com/ext/map/...")
```

### Returns

JSON: `{ok, questions, error, log}`

- `ok`: true if all questions completed
- `questions`: number processed
- `error`: present only on failure
- `log`: console output (truncated)

### How It Works

1. Navigates/refreshes the page
2. Injects `smartbook.js` (JSON.parse interceptor) immediately during load
3. Waits for API responses to be captured
4. Runs `window.auto()` — loops through questions, fills answers, clicks confidence, clicks next, just wait for it to finish

---

### 2026-05-18 13:16 UTC


## 2026-05-17 — Matching question loop fix

**Root cause:** Two bugs conspired to cause infinite loops on consecutive matching (drag-and-drop) questions:

1. **Race condition in `isReadingPage()`** — After Python handles a matching question and clicks Next, the SPA transitions to the next question. `auto()` is called again via the while loop's `continue`. If the DOM hasn't finished rendering, `isReadingPage()` returns true (no choices visible yet), triggering `clickContinue()`/`clickNext()` which could double-click and skip a question or create a confused state.

2. **No stuck-question detection** — If CDP drag or confidence click silently failed, the page stayed on the same question. `auto()` would be called, find `q = null` (already consumed), timeout waiting for data, return `done`. But `retries = 0` in the matching handler prevented the outer loop from ever giving up. Python would retry, auto() would return the same matching answer, Python would try drag again — infinite loop.

**Fixes applied:**

- **`smartbook.js`**: `isReadingPage()` now uses a `MutationObserver` to track DOM changes. If the DOM has changed within the last 1.5 seconds, it returns `false` (treats page as "still loading") instead of declaring it a reading page. This prevents premature continue/next clicks during SPA transitions.

- **`agent_helpers.py` matching handler**: 
  - `same_question_streak` counter: if the same matching answer appears 3 consecutive times, the function returns an error instead of looping forever.
  - Confidence and Next button clicks now retry up to 3 times with 1s waits, instead of firing once and hoping.
  - Element-not-found errors during drag coords extraction are now caught and retried (the SPA may have moved elements between checks).
  - `retries` is now incremented at the top of every while iteration (not reset in matching handler), so the loop always has an upper bound.
  - `q_count += 1` moved to after successful drag (not at entry), so failed drags don't inflate the count.


---

### 2026-06-07 00:38 UTC

## 2026-06-06 — Repo helper synced from successful SmartBook runs

Tracked `agent-workspace/smartbook.js` has been updated from the working `/tmp/smartbook.js` used for IBUS SmartBook Ch1/Ch2. Important fixes now in the repo copy:

- UUID/string answer values are mapped back to choice positions (`key`, `id`, `choiceId`, `value`) instead of assuming numeric answer indices.
- `window.__sbStats` and `window.__lastParsedQ` expose lightweight progress/debug counters.
- `clickContinue()` now prefers question navigation (`Continue Questions`, `Start Questions`, etc.) and hard-blocks resource/reading paths (`Continue Reading`, `Read Book`, `Launch eBook`, etc.) that caused PDF/resource detours.
- `smartbook_complete()` now prefers the tracked repo script before `/tmp/smartbook.js`; `/tmp` is fallback only.