# 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

```bash
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.