ismis-helper/AGENTS.md

ISMIS Helper — Agent Guide

Guidance for AI coding agents and contributors working in this repository.

What this is

A Firefox/Chrome MV3 extension that automates the USC ISMIS student portal (ismis.usc.edu.ph): auto-login, privacy-policy auto-accept, and a Study Load PDF export that visually matches the official document (bundled Segoe UI fonts, USC logo, course table, units total).

No build step is required for the source itself; scripts/build.js only packages the two browser variants into dist/.

Commands

npm install                       # dev deps (only needed for tests)
npm test                          # run the test suite (node --test)
node scripts/build.js all         # build both browser zips -> dist/
node scripts/build.js firefox     # build just firefox
node scripts/build.js chrome      # build just chrome
node scripts/build.js all --version 1.3.0   # versioned zips
npm run build                     # shorthand for `node scripts/build.js all`

Never edit anything under dist/ — it is generated and gitignored.

Repo layout

• manifest.json — Firefox manifest (the single source of truth). The Chrome manifest is derived at build time.
• background.js — message handler; builds the PDF via pdf.js and downloads it. Also has the cross-browser browser.*/chrome.* alias shim at the top.
• content.js — runs on ismis.usc.edu.ph: auto-login, privacy modal auto-accept, scrapes the study load, injects the on-page Download PDF button.
• parsers.js — pure HTML-scraping helpers (study load table, profile page, offered courses, filtering/summing).
• pdf.js — builds the PDF; exports buildStudyLoadPdf plus formatting helpers (compactProgram, formatSchedule, formatFullName, formatTeacher, deriveDateRange, truncateToWidth).
• popup.html / popup.js / popup.css — settings UI (profiles, master toggle, PDF settings like truncation and Year Level).
• libs/ — vendored pdf-lib.min.js and fontkit.min.js (needed to embed the custom Segoe UI fonts).
• assets/ — the transparent PNG logo and fonts/Segoe-UI*.ttf.
• icons/ — 16/32/48/128 extension icons.
• scripts/build.js — zero-dependency packaging script for both browsers.
• .gitea/workflows/build.yml — Gitea Actions: builds + tests on push, creates a Gitea Release with both zips when a v* tag is pushed.
• test/ — node --test suite (pdf.test.js, parsers.test.js).

Build model (Firefox vs Chrome)

• The root is the Firefox source: manifest.json uses background.scripts (multiple files) and browser.* APIs.
• The Chrome build derives a manifest with "background": { "service_worker": "background.chrome.js" } and assembles that single worker by concatenating, in order: libs/fontkit.min.js → libs/pdf-lib.min.js → pdf.js → background.js.
• The cross-browser shim (top of background.js, content.js, popup.js) aliases browser to chrome when the former is absent. It is a no-op in Firefox.
• scripts/build.js excludes test/, docs/, scripts/, dist/, and .git from the packaged output.

Conventions & constraints

• Plain ES5+ JavaScript. No framework, no bundler, no build step for the source.
• Use Promise-based browser.* APIs (Chrome MV3 supports browser.*; the shim covers builds that only expose chrome.*).
• Login profiles are stored plaintext in browser.storage.local. At most one profile is enabled at a time; a master enabled toggle disables all behavior.
• The on-page Download PDF button must never touch another window's DOM; it sends a message to the background which downloads via browser.downloads.download({ saveAs: true }) (blob → object URL).
• If you change pdf.js layout constants, verify against the reference PDF (/Users/adrianbonpin/Downloads/BSIT - Y3S1 - Study Load.pdf) and re-check the position measurements, since offsets can be font-metric dependent.
• Keep docs/ and dist/ out of git (they are ignored).

Workflow

1. Run npm test before and after changes.
2. Build (npm run build) to make sure both variants assemble.
3. Manually load dist/firefox in Firefox (about:debugging) and dist/chrome in Chrome (chrome://extensions) to verify PDF generation.