# ISMIS Helper — Firefox Extension Design

**Date:** 2026-08-18
**Status:** Approved
**Target site:** `https://ismis.usc.edu.ph` (USC ISMIS student portal)

## Overview

A personal Firefox extension (Manifest V3, no build step) that improves the USC ISMIS
student portal experience. It provides three features:

1. **Auto-login** — auto-fill and auto-submit the login form from a saved profile.
2. **Auto-accept Privacy Policy** — dismiss the recurring privacy-policy modal.
3. **Study Load PDF** — generate a PDF of the student's study load, replicating the
   official ISMIS document, including course descriptions looked up from the
   Offered Courses endpoint.

A single **master toggle** disables all extension behavior on the portal.

## Architecture

Single MV3 extension, plain JavaScript, no bundler.

```
ismis-helper/
├── manifest.json          # MV3 manifest, permissions, content script, popup
├── background.js          # service worker: message routing + PDF generation
├── content.js             # runs on ismis.usc.edu.ph: auto-login, privacy, scraping
├── popup.html             # popup UI
├── popup.js               # popup logic
├── popup.css              # popup styles
├── libs/pdf-lib.min.js    # vendored pdf-lib library
└── icons/                 # extension icons (16, 32, 48, 128)
```

### Permissions (manifest.json)
- `storage` — persist profiles and the master toggle.
- `downloads` — save the generated Study Load PDF.
- `activeTab` — access the current tab for scraping.
- Content script matches `https://ismis.usc.edu.ph/*`.

## Component 1 — Auto-login

- Content script runs on `https://ismis.usc.edu.ph/Account/Login`.
- Reads the active (first enabled) profile from `browser.storage.local`.
- Locates the username and password input fields (by common `name`/`id` values such
  as `UserName`, `Password`, `username`, `password`).
- Fills both fields, then submits the form (auto-submit).
- If no profile is enabled, or the master toggle is off, does nothing.

## Component 2 — Auto-accept Privacy Policy

- On any portal page, if the privacy modal `#myModal` is present and visible:
  - Check the `#Confirmation` checkbox ("I have read and understood the Privacy
    Policy Statement").
  - Click the `#Submit` button (Continue), which is disabled until the checkbox is
    checked.
- Gated by the master toggle.

## Component 3 — Profiles

- Stored in `browser.storage.local` under key `profiles` as an array of:
  `{ id, name, username, password, enabled }`.
- Popup provides add, edit, delete, and enable/disable per profile.
- The first profile with `enabled === true` is used for auto-login.
- Master toggle stored under key `enabled` (boolean).

## Component 4 — Study Load PDF

### Scrape
- On the Study Load page, parse the course table with columns:
  **Group #, Course Code, Schedule, Faculty, Units, Status**.
- Read the total-units footer (e.g. `12.00 Units / Total Units: 18.00`).
- Header fields (student ID, name, program, year level, semester, date enrolled)
  are scraped when present on the page; otherwise they are entered manually in the
  popup before generating the PDF.

### Description lookup
- For each unique course code, POST to
  `https://ismis.usc.edu.ph/CourseSchedule/CourseScheduleOffered` with form data:
  - `Courses=<course code>`
  - `AcademicPeriod=<selected value>`
  - `AcademicYear=<selected value>`
  - `__RequestVerificationToken=<token from page>`
  - plus the `AjaxFormVM.*` fields observed in the HAR capture.
- Parse the returned HTML table to extract the **Course Description** for the course.
- If lookup fails for a course, leave the description blank and continue.

### Manual fallback
- If scraping finds no table, the popup shows a manual entry form for the same fields
  (including optional course descriptions).

### PDF generation
- `background.js` uses **pdf-lib** to build the PDF replicating the official layout:
  - Header block: semester, "STUDENT'S STUDY LOAD", date range, date enrolled,
    student ID, name, program, year level.
  - Course table: Course, Course Description, Units, Teacher, Group, Note
    (status: REGULAR/PARALLEL/DISSOLVED), Schedule.
  - Footer: total units, printed-by line.
- Downloads the PDF via the `downloads` API.

## Data flow

```
popup ──message──▶ background ──message──▶ content (scrape + description lookup)
   ▲                                              │
   └────────────── data back ◀────────────────────┘
        │
        ▼
   pdf-lib → download
```

## Error handling

- Master toggle off → no extension behavior on the portal.
- No enabled profile → no auto-login.
- Description lookup fails for a course → blank description, PDF still generated.
- Scrape fails entirely → manual entry form in the popup.
- Login fields not found → log a warning, no crash.

## Testing

- Load via `about:debugging` → "Load Temporary Add-on".
- Verify auto-login on the login page.
- Verify privacy modal auto-accept.
- Verify profile add/edit/delete/toggle and master toggle.
- Verify Study Load PDF generation: scrape, description lookup, manual fallback.