From 793748abe52c4fb3d17921e9769abdc3ba6c1eb3 Mon Sep 17 00:00:00 2001
From: adrianbonpin <adrianbonpin@users.noreply.github.com>
Date: Tue, 18 Aug 2026 15:08:06 +0800
Subject: [PATCH] Add ISMIS Helper design spec

---
 .../specs/2026-08-18-ismis-helper-design.md   | 123 ++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-18-ismis-helper-design.md

diff --git a/docs/superpowers/specs/2026-08-18-ismis-helper-design.md b/docs/superpowers/specs/2026-08-18-ismis-helper-design.md
new file mode 100644
index 0000000..cbcb4da
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-18-ismis-helper-design.md
@@ -0,0 +1,123 @@
+# 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`).
+
+### 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, 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.