Skip to content

Browser extension MVP: "Download PDF" on GitHub markdown views (MAK-200) - #1

Merged
lecstor merged 5 commits into
mainfrom
clanker/2dcc3f01-browser-extension-mvp-download-pdf-butto
Oct 13, 2026
Merged

lecstor merged 5 commits into
mainfrom
clanker/2dcc3f01-browser-extension-mvp-download-pdf-butto

Conversation

@lecstor

@lecstor lecstor commented Oct 12, 2026

Copy link
Copy Markdown
Member

Closes MAK-200. The repo's only line is main (no staging/integration branch exists), so this PR targets main.

What

MV3 + TypeScript extension, one build producing dist/chromium and dist/firefox (plus zips). On a GitHub .md/.markdown file view — and on a repo home's rendered README — a Download PDF button renders the file through POST https://makespdf.com/api/v1/md and downloads <file-stem>.pdf.

  • Markdown is fetched raw through the page's session (.../raw/<ref>/<path>, works for private repos and refs containing /); the rendered page is never scraped.
  • Relative images (![](x.png), <img src>) are fetched with the session and inlined as data: URIs; a failed image stops the export and names it (MAK-191 precedent). 5 MB/image, 20 images/document, absolute URLs left to the server.
  • Anonymous by default (promo carve-out); Authorization: Bearer <key> only when a key is saved in the options page (storage.local, never synced).
  • X-MakesPDF-Client: browser-extension/<version>+<build> baked per package (+chromium / +firefox), pinned by unit tests against the built bundles.
  • Errors mirror the VS Code/Zed wording: 401 key/no-key, 429 + sign-up hint, 400 (page cap), 413.
  • Turbo soft navigation: idempotent re-injection on Turbo events, DOM mutations and a 1 s poll — never two buttons, never a stale binding.
  • Minimal permissions: storage, content script on github.com, host permission for makespdf.com. No <all_urls>, no downloads.

Review fixes — commit 98f49f7 (the scoped follow-up pass)

The adversarial review gate's findings, all with regression tests:

  1. Repo-home README filename cases — GitHub's raw route is a case-sensitive path lookup, so README.md alone 404s for lowercase/Readme.md repos (verified against sindresorhus/awesome); the home fetch now tries the six common spellings.
  2. Whole-document image cap — the pre-flight counted only relative refs, but the server's 20-image cap counts every img src and skips the extras silently; the pre-flight now counts all of them.
  3. Home button placement — a rendered README's own /owner/repo/raw/... link looked like the header's Raw button and planted the button inside the README; the home button always floats.
  4. Firefox Xray bug (found by the new Firefox smoke) — base64FromBytes spread a typed array into String.fromCharCode(...), which in Firefox content scripts throws Permission denied to access property "constructor" and broke every image inlining. Fixed by reading code units into a plain array.

Manual smoke record (doneWhen 7)

Both packages were built from 98f49f7 and driven end to end:

Chromium — node smoke/chromium-smoke.mjs (Playwright, headless, SMOKE_REF = this branch), scripted against production:

  • blob view of smoke/fixture.md: button injected; click → real anonymous render → fixture.pdf, 45,576 bytes, %PDF-
  • soft navigation to smoke/second.md: exactly one button, still bound to the new file → second.pdf, 42,147 bytes
  • repo home (makesPDF/makespdf-vscode-plugin): floating button present

Firefox — node smoke/firefox-smoke.mjs (real Firefox, web-ext temporary install, Marionette-driven; new in this PR):

  • same flow: button injected → fixture.pdf 45,576 bytes → soft nav leaves one button → second.pdf 42,147 bytes → repo-home button present

Still manual (not automatable here — needs a signed-in browser session): a private-repo file with relative images. The public fixture exercises the same raw-route + session-cookie path.

Verification

  • npm run typecheck — clean
  • npm test — 94 tests / 10 files, all pass (URL matching incl. slash refs, path resolution, image limits and failure messages, HTTP error mapping, header literal per built package, controller/soft-nav idempotence)
  • npm run build + npm run verify:packages — both packages build; structural checks pass
  • web-ext lint (Firefox package) — 0 errors; 1 warning MISSING_DATA_COLLECTION_PERMISSIONS — the AMO data-consent key is deliberately deferred: it is only required for store submission (this MVP ships no store assets/icons), and declaring it forces strict_min_version from 115 to Firefox 140 (addons-linter enforces the pairing), which would silently drop 115–139 for no current benefit. Recorded as a decision on the task; a one-line change when the store-submission task happens.

Notes for the reviewer

  • CI runs on this PR (typecheck → test → build → verify:packages).
  • The Firefox smoke is not in CI (it needs a browser + network + web-ext); the --headless Marionette driver is documented in smoke/firefox-smoke.mjs.
  • Known MVP gaps are listed in the README (reference-style images, root-relative paths with slash refs, no icons yet).

lecstor and others added 5 commits October 13, 2026 08:20
…smoke

Native fetch throws Illegal invocation when invoked as a property of an
object (background deps, adapter instance) — found by the real-browser
smoke. boundFetch() is now the single place fetch is bound.

Chromium smoke (scripted, against production): button injected on a blob
view, real anonymous render downloaded as fixture.pdf, soft navigation to
second.md leaves exactly one working button, repo-home README button
present. Firefox half remains manual.
… Firefox Xray base64; scripted Firefox smoke

Adversarial review findings, each with a regression test:

- Repo-home READMEs: the raw route is a case-sensitive path lookup, so
  README.md/readme.md/Readme.md/…markdown are all tried.
- The 20-image pre-flight now counts every img src (relative, absolute,
  data:), because the server's cap counts the whole document and skips the
  extras without a trace.
- The home button always floats; a rendered README's own /raw/ link is page
  content, not the header's Raw button, and must not become an insertion
  point.
- base64FromBytes no longer spreads a typed array: in Firefox content
  scripts that spread trips the Xray compartment check ('Permission denied
  to access property "constructor"'), which broke every image inlining.
  Found by the Firefox smoke.
- smoke/firefox-smoke.mjs drives the real Firefox over Marionette (web-ext
  temporary install) and runs the same flow as the Chromium smoke; it
  caught the Xray bug end to end.
@lecstor
lecstor merged commit 5391461 into main Oct 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant