# Incident: `ReferenceError: enableTraining is not defined` (web, PIN confirm)

**Status:** Fixed in **8.1.10** (removes stale identifier usage; see `CHANGELOG.md`).  
**Build guard:** `scripts/verify-removed-props.cjs` runs after `verify-package-entries` in `npm run build` to block reintroducing `enableTraining` under `src/`.

---

## Symptom

In the browser (web bundle `onairos.bundle.js`), after the user taps **Confirm** on the **PIN** screen, the console shows:

```text
Uncaught (in promise) ReferenceError: enableTraining is not defined
```

This is a **host-app–independent** SDK error: the identifier is not a missing prop from the integrator; it was **not declared anywhere** in the v8 `OnairosButton` prop list.

---

## Root cause

1. **v8.0.0** removed the public prop `enableTraining` in favor of `trainingScreenMode` (and related props). See `docs/ONAIROS_BUTTON_PROPS.md` and the breaking-change notes in `CHANGELOG.md`.

2. A **later** change added new branches in `src/onairosButton.jsx` that still **referenced** `enableTraining` as if it were a variable in scope. After the prop was removed, that name is a **free identifier** → **ReferenceError** the first time that branch runs.

So the failure is not “8.1.9 regressed the API” in isolation; it is **stale code** that referenced a **removed** API, combined with a **rare code path** (see below).

---

## Git history (who, when, purpose)

### Commit that removed the API (intentional breaking change)

| Field | Detail |
|--------|--------|
| **Hash** | `42a2693` |
| **Date** | 2026-04-30 20:12 +0400 |
| **Author / committer** | joyalkenus |
| **Purpose** | v8.0.0: consolidate training props — remove `enableTraining`; introduce `trainingScreenMode` (`mock` \| `fast` \| `real` \| `none`). |

### Commit that reintroduced the identifier in new logic (accidental)

| Field | Detail |
|--------|--------|
| **Hash** | `625d270` |
| **Land date (committer)** | 2026-05-02 (merge/rebase timing; author date on patch may be earlier) |
| **Author** | joyalkenus |
| **Committer** | Anushka Jogalekar |
| **Purpose** | `fix(web): minimal backgroundLoadData handoff flow` — PIN/onboarding handoff, silent training when `trainingScreenMode === 'none'`, `backgroundLoadData` behaviour, etc. |

**Important:** `42a2693` is an **ancestor** of `625d270` on `main`. So the handoff work landed **after** `enableTraining` was removed from props; the new branches should have used `trainingScreenMode` / `resolvedTrainingMode` only. The review did not catch the leftover symbol.

---

## Why QA saw this on **8.1.9** / PIN only, not “every” v8 test before

Several factors stack; **mobile vs desktop browser is not the primary explanation** (same JS, same bundle logic).

1. **Path-specific:** The bad references lived in flows that run only after **PIN completion** (and similar onboarding-return logic), for **non–special-app** integrations (`webpageName` does not match wrapped / Valentine / Lunar / Ascend shortcuts). Other flows never executed those branches → **no error**.

2. **Same bug may exist across patch versions:** If **8.1.8** and **8.1.9** were built from the same `main` lineage after `625d270`, the **source bug can be identical**. Seeing it only on **8.1.9** often reflects **which scenario was exercised** (fresh signup → PIN → confirm) rather than a unique regression in the patch number.

3. **Session / user state:** Returning users with **`pinCreated` already true** often **never hit** the PIN confirm handler the same way as a **first-time PIN** flow.

4. **Special-app detection:** `getAppFlags()` depends on **`webpageName`** substrings (e.g. wrapped / lunar / valentine / ascend). Those paths **skip** the broken branch earlier → **no ReferenceError** even on PIN.

5. **Coverage gap:** “Tested all of v8” without a **full** pass of **normal web app → create PIN → confirm** can miss this entirely.

---

## Resolution

- **Code:** Remove all references to `enableTraining` in `onairosButton.jsx`; express behaviour with `trainingScreenMode` / resolved mode and existing platform-change flags (**8.1.10**).
- **Prevention:** `scripts/verify-removed-props.cjs` fails the build if `enableTraining` appears under `src/`.

---

## References

- `CHANGELOG.md` — **[8.1.10]**
- `docs/ONAIROS_BUTTON_PROPS.md` — v8 migration off `enableTraining`
- `scripts/verify-removed-props.cjs` — regression guard