ismis-helper/docs/superpowers/specs/2026-08-18-ismis-helper-design.md

# 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. **Printable Study Load** — an on-page "Download PDF" button on the Study Load page
   that opens a print-ready Letter-size document replicating the official ISMIS Study
   Load (with course descriptions looked up from the Offered Courses endpoint),
   triggering the browser print dialog so the user can print or "Save as PDF".

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
├── content.js             # runs on ismis.usc.edu.ph: auto-login, privacy, button, print flow
├── parsers.js             # UMD: table/profile/offered-courses parsing + filtering
├── printdoc.js            # UMD: buildStudyLoadHtml (Letter-size printable document)
├── popup.html             # popup UI (master toggle + profiles)
├── popup.js               # popup logic
├── popup.css              # popup styles
└── icons/                 # extension icons (16, 32, 48, 128)
```

### Permissions (manifest.json)
- `storage` — persist profiles and the master toggle.
- `host_permissions` — `https://ismis.usc.edu.ph/*` for the content script.
- No background, no `downloads` permission (the print flow uses `window.open` +
  the browser's print dialog).

## 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 — Printable Study Load

### 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 below the `12.00 Units / Total Units: 18.00`
  footer, styled like the page's buttons (`btn green pull-right`).

### 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.

### Print document
- `buildStudyLoadHtml` (printdoc.js) produces a self-contained HTML document at the
  official dimensions (**Letter, 8.5in × 11in** via `@page`), 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: …").
- The button opens this document in a new window and auto-triggers
  `window.print()`, so the user prints or "Save as PDF" at the official dimensions.
- All scraped/entered values are HTML-escaped.

## Data flow

```
Study Load page ──▶ content script (scrape + filter + description lookup)
                       │
                       ▼
              buildStudyLoadHtml (printdoc.js)
                       │
                       ▼
        window.open + window.print()  →  print / Save as PDF (Letter)
```

## 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, document still opens.
- No enrolled (non-DISSOLVED) courses → error toast, no window opened.
- Popup blocked → toast explaining popups must be allowed for the site.

## Testing

- Node `node:test` suites: parsers (table/profile/offered-courses/filter/sum) and
  printdoc (page size, layout, escaping, auto-print).
- 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 below the total-units footer,
  excludes DISSOLVED courses, and opens the Letter-size printable document.