opportunities-extension/docs/refactoring.md

# Incremental Refactoring Record

## Stage 1: Characterization Baseline

Stage 1 initially added tests and documentation only, before any runtime extraction.
The following records that historical baseline. The completed integration and
remaining verification gaps are recorded under "Completed Extraction Stages" below.

### Coverage Added

`tests/characterization.test.cjs` contains 22 test cases using Node's built-in
test runner, assert and vm. `tests/support/characterization.cjs` provides isolated
fixtures: no real browser cookies, account identifiers, tokens or network access.
Unexpected fetches reject rather than falling through to global fetch.

- Exact current manifests and source/output equality, with classic-script syntax validation.
- Disallowed-origin initialization and reinjection when the tile already exists.
- Fiscal boundaries, leap years, rolling quarters and unsupported RENEWALS.
- Full opportunity query payload, pagination offsets/counts and stale request versions.
- Filter storage round-trip, WON_PENDING, search, numeric sort, reference reset and malformed preferences.
- Missing-cookie tokenrelay recovery and existing 400/401/403 retry limit.
- Chrome callback and Firefox promise mocks for background dispatch, storage, cookies and tabs.
- Product pagination, default/custom TTL, concurrency limit, in-flight sharing and partial errors.
- Persisted product reads after recreating the background context; storage failures and stalled pages.
- XSRF discovery, recovery timeout, successful recovery and temporary-tab cleanup.
- SPA credential selection, account payloads, encoded identifiers and debug envelopes.
- Invalid messages, network errors, HTTP 401 and HTTP 200 invalid JSON in consumption.

Existing suites remain intact: consumption normalization/requests, consumer-session
recovery, AI summary rendering/state, scoped token reuse/expiry and bounded retry.
Tests for the current security defects are deliberately not encoded as acceptable
behavior. They belong to separately approved fixes.

### Former Temporary Test Seam

The original content IIFE had no exports, so baseline tests initially exposed
functions before initialization with a guarded source marker. That temporary
mechanism is now removed. Tests use the actual application factories through
`tests/support/application.cjs`, without replacing source strings. Background
integration tests still execute the production listener and asynchronous replies.

### Running Checks

```sh
npm test
npm run check
```

Without npm, use the Node commands in package.json individually. The new suite is:

```sh
node tests/characterization.test.cjs
```

At baseline, `build.mjs --check` did not compare output contents. It now checks
both generated manifests and both scripts byte-for-byte against composition.
Characterization tests retain the exact manifest expectations.

Stage-1 verification on Node.js v24.19.0:

| Command | Result |
| --- | --- |
| `node --check src/content.js` and `node --check src/background.js` | Passed |
| `node --check tests/support/characterization.cjs` | Passed |
| `node tests/consumptionTrend.test.cjs` | Passed |
| `node tests/consumerTokenSessionRetry.test.cjs` | Passed |
| `node tests/aiSummary.test.cjs` | Passed |
| `node tests/characterization.test.cjs` | 22 passed, 0 failed |
| `node scripts/build.mjs --check` | Passed; distribution equivalence also checked by the suite |
| `git diff --check` | Passed |

The individual commands from the npm scripts were executed directly. No build
regeneration was needed because runtime sources and the build were unchanged;
`git diff -- src dist scripts/build.mjs` was empty.

### Verification Limits

- API mocks are not proof of Chrome/Edge/Firefox compatibility or real authentication.
- Recreating a VM tests cache rehydration, not actual service-worker suspension or job recovery.
- DOM mocks do not prove layout, focus, accessibility or SPA lifecycle correctness.
- The original visual fixture used eval. The completed extraction removed it and
  serves the composed factory through a normal local script instead.
- No installed-browser smoke test or live Fusion request was performed in stage 1.
- No JavaScript export/generator feature was located. Do not create a generators
  directory until its actual source and standalone-output contracts are identified.

## Separate Security and Reliability Backlog

These are preexisting observations, not authorized functional changes in this refactor.

| Issue | Evidence/impact | Separate change to evaluate |
| --- | --- | --- |
| Debug redaction after truncation | Invalid/truncated JSON is returned unmasked by formatDebugBody; reproduced with a synthetic token | Redact before truncation, fail closed on malformed bodies, test all response shapes |
| Debug secrets and shared DOM | Raw headers/bodies are retained for the reveal control; revealed text is in page DOM | Review retention, safe diagnostic schema and whether revealing credentials remains acceptable |
| Cookie store selection | Lookup scans all stores instead of binding to sender account/container | Scope selection to the requesting context and test multi-account behavior |
| Product cache isolation | Cache and in-flight keys use OptyNumber only | Design identity partitioning and explicit cache migration/retention policy |
| Privileged message validation | No explicit sender identity/origin check; supplied header names are accepted | Validate senders/messages and allowlist headers without introducing an arbitrary proxy |
| Session tab retry | Opening failures retry indefinitely; interruption can strand work | Decide cancellation/limits and worker lifecycle recovery explicitly |
| DOM lifecycle | Observer can remain active; guards do not cover every reinjection/resize path | Define ownership/disposal and characterize navigation before changing behavior |
| Token expiry | General/SPA tokens have policies different from Sales Common | Review independently; do not unify policies as part of extraction |

Never include real secrets in repro cases, snapshots, documentation or test output.
Do not add persistent token storage to compensate for worker termination.

## Completed Extraction Stages

All modules listed below are integrated through `scripts/sources.cjs` and the
two composition roots. Former `src/content.js` and `src/background.js` were removed;
their names remain only for the generated distribution scripts. No version change,
commit, publication, runtime dependency, permission expansion or CSP change occurred.

| Stage/responsibility | Files/boundaries | Preserved contracts and evidence | Remaining risk/next safe step |
| --- | --- | --- | --- |
| Build and pure logic | `scripts/compose.cjs`, `sources.cjs`; fiscal-periods, formatters, consumption model | Classic IIFEs, exact manifests, dates, payload/normalization tests; syntax checked per source and composed bundle | Native browser package loading still needs a smoke test |
| Platform and dispatch | `platform/`, `background/main.js`, `messages.js`, `shared/messages.js` | Sync listener registration, callback/promise mocks, async responses, sender-frame progress and unknown-message behavior | Sender validation is a separate security change |
| Auth and HTTP operations | `auth/`, `services/` | Credential selection, scoped-token reuse/expiry, 401/403 retry, missing-cookie and HTML-session recovery, request/debug envelopes | Real SSO and worker suspension not simulated completely |
| Products | `features/products/` | Four-worker queue, pagination, TTL, cache restore, in-flight sharing, partial errors and expansion behavior | Existing identity/cache-retention policy unchanged |
| Content features | opportunities, preferences, AI-summary, consumption and debug factories/state | Filter/search storage round-trip, sorting, stale requests, AI safe text, plan/period controls, preserved labels and DOM | Existing DOM lifecycle and narrow-screen limitations remain |
| Bootstrap, CSS and documentation | `content/main.js`, `background/main.js`, application roots, styles; README/docs | CSS byte-identical to original (hash test); factories connected, no orphan sources or peer-factory dependencies; old marker/eval fixture removed | Native browser matrix below remains pending |

The automated suites were run after the initial extraction and again after the
platform/auth refinements, cleanup and final composition. Intermediate verification
found and corrected test-harness expectations for source inventory and fixture
callback messaging; no production auth, cookie or session policy was changed.

### Final Automated Verification

Executed with Node.js 24.19.0, directly through the package-script equivalents:

| Command | Result |
| --- | --- |
| `node scripts/build.mjs` | Both packages regenerated; all source/composed JavaScript syntax valid |
| `node scripts/test.cjs` | All five suite files passed: AI, architecture (6 cases), characterization (22 cases), session recovery, consumption |
| `node scripts/build.mjs --check` | Generated scripts/manifests match source composition |
| `git diff --check` | No whitespace errors |

There is no configured linter. Syntax validation uses Node's JavaScript parser
through vm.Script, not eval or new Function in the extension. No generators feature
was located; standalone JavaScript generation therefore has no feature-specific
snapshot to assert. The architectural suite verifies deterministic composition,
source coverage, dependency injection, independent per-frame state and lazy
localStorage failure handling. Feature suites use synthetic credentials only.

### UI Smoke Verification

The loopback fixture was exercised in the Codex in-app browser, using the same
composed content factories with injected synthetic runtime/fetch/storage adapters.
It is not an installed extension and does not validate privileged browser APIs.

- Paginated synthetic opportunities, product progress/counts and dashboard rendered.
- Search text/filter remained after closing and reopening the modal.
- Light/dark toggle and product expansion retained the existing presentation.
- AI text, including literal HTML delimiters, appeared as text above the product table.
- Preferences retained checkbox/cache-duration selections after Save and reopen.
- Cloud Consumption opened with plan tabs; weekly default, daily switch, alternate
  plan and series visibility toggles worked. Debug listed scoped relay and AI calls.
- Screenshots inspected at 1920x1080, 1280x720 and 390x844. Desktop columns rendered
  with complete Last Update Date and WON_PENDING. Existing compact-table scrolling
  and clipping at 1280 remain unchanged; mobile controls stack. This is not a full
  mobile workflow/accessibility audit and no layout redesign was included.
- No console errors were reported during the exercised flows.

### Outstanding Native Browser Matrix

| Target | Package/runtime | Status |
| --- | --- | --- |
| Chrome | `dist/chromium`, MV3 service worker | Not run as an installed extension |
| Edge | `dist/chromium`, MV3 service worker | Not run as an installed extension |
| Firefox | `dist/firefox`, MV3 background scripts | Not run as an installed extension |

The available automation connection exposed the in-app browser and a Brave
profile, not Chrome, Edge or Firefox. No live Fusion requests, user-session access
or extension installation were used to substitute for the missing native tests.
Actual suspension/reactivation, container routing and SSO remain unverified.

The next safe validation is to load the generated packages in an authorized test
profile in each target browser, then exercise tile insertion, modal reopen,
filters/preferences, products, AI, consumption, debug and background restart.
Resolve the separately listed security issues only in explicitly approved changes.

See [the native browser checklist and execution record](browser-smoke.md) for the
2026-09-17 follow-up. Local tests and output checks passed again; Chrome/Edge were
installed but not connected to automation. Native verification remains pending
while the user connects those browsers.