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.