# 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** — an on-page "Download PDF" button on the Study Load page that
   generates a PDF replicating the official ISMIS Study Load document (Letter size,
   with course descriptions looked up from the Offered Courses endpoint) and
   downloads it directly.

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

## Architecture

Single MV3 extension, plain JavaScript, no bundler. No background script — all logic
runs in the content script (scraping and print-document building happen in-page).

```
ismis-helper/
├── manifest.json          # MV3 manifest, permissions, content script, popup, background
├── background.js          # message handler: build PDF (pdf-lib) + download via downloads API
├── content.js             # runs on ismis.usc.edu.ph: auto-login, privacy, button, scrape
├── parsers.js             # UMD: table/profile/offered-courses parsing + filtering
├── pdf.js                 # UMD: buildStudyLoadPdf (Letter PDF, official layout, pagination)
├── popup.html             # popup UI (master toggle + profiles)
├── popup.js               # popup logic
├── popup.css              # popup styles
├── libs/pdf-lib.min.js    # vendored pdf-lib library (used by background)
└── icons/                 # extension icons (16, 32, 48, 128)
```

### Permissions (manifest.json)
- `storage` — persist profiles and the master toggle.
- `downloads` — save the generated Study Load PDF.
- `host_permissions` — `https://ismis.usc.edu.ph/*` for the content script.
- Background loads `libs/pdf-lib.min.js` + `pdf.js` via `background.scripts`.

## Background script
- `background.js` handles the `generate-pdf` message from the content script:
  builds the PDF via `ISMIStools.buildStudyLoadPdf`, wraps the bytes in a Blob,
  downloads via `browser.downloads.download({ saveAs: true })`, and revokes the
  object URL when the download reaches `complete`/`interrupted` (and on failure).

## Component 1 — Auto-login

- Content script runs on `https://ismis.usc.edu.ph/Account/Login`.
- Reads the active (enabled) profile from `browser.storage.local`.
- Locates the username and password input fields (`name`/`id` = `Username` /
  `Password`, with fallback variants).
- 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.
- Only one profile can be enabled at a time (enabling one disables the others);
  that profile is used for auto-login.
- Master toggle stored under key `enabled` (boolean).

## Component 4 — Study Load PDF

### On-page button
- The content script watches the Study Load page (`#StudyLoad`). When the course
  table appears (after the user selects academic period/year and searches), it
  injects a **"Download PDF"** button inline with the
  `12.00 Units / Total Units: 18.00` footer (button on the left, units text on the
  right, via a flex row), styled like the page's buttons (`btn green`).

### Scrape
- Parse the course table (columns: Group #, Course Code, Schedule, Faculty, Units,
  Status) via `parseStudyLoadTable`.
- **Header info** (full name, student ID, program, year level, semester) is scraped
  from the **My Profile** page (`/Manage/Student`).

### Filtering
- **DISSOLVED courses are excluded** (`filterStudyLoadCourses`).
- Total units = sum of the included courses' units (`sumUnits`).

### Description lookup
- For each unique course code, POST to
  `https://ismis.usc.edu.ph/CourseSchedule/CourseScheduleOffered` with the
  `__RequestVerificationToken` and selected `AcademicPeriod`/`AcademicYear`, then
  parse the returned table for the **Course Description**.
- If lookup fails for a course, the description is left blank and generation
  continues.

### PDF generation
- `pdf.js` (`buildStudyLoadPdf`, using **pdf-lib**) builds a Letter-size (612×792pt)
  PDF replicating the official layout: title block (STUDENT'S STUDY LOAD, semester,
  date range, date enrolled), student info row (ID, name, program, year level), the
  course table (GROUP, COURSE, COURSE DESCRIPTION, TEACHER, UNITS, NOTE — NOTE is
  the status), and a footer (total units, "Printed by: …"). Multi-page
  pagination re-draws the table header. NOTE column is wide enough for `REGULAR`.
- The content script sends the data to the background (`generate-pdf`), which
  downloads the PDF via the `downloads` API (`saveAs: true`).

## Data flow

```
Study Load page ──▶ content script (scrape + filter DISSOLVED + description lookup)
                       │
                       ▼  browser.runtime.sendMessage({ type: 'generate-pdf', data })
              background.js (pdf-lib buildStudyLoadPdf)
                       │
                       ▼
              browser.downloads.download → Study Load PDF file
```

## 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.
- No enrolled (non-DISSOLVED) courses → error toast, no download.
- Download fails → error toast; object URL is revoked.

## Testing

- Node `node:test` suites: parsers (table/profile/offered-courses/filter/sum) and
  pdf (valid Letter PDF output).
- 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 the on-page Download PDF button: appears inline with the total-units
  footer, excludes DISSOLVED courses, and downloads a Letter-size PDF.