- Update the "Getting the Code" section to specifically mention Mozilla Firefox, since while the development viewer *works* it may look slightly "broken" in Chromium-based browsers. (This is caused by a lack of support for unprefixed CSS properties, e.g. `mask-image`, however this does *not* affect the built PDF.js viewer.)
- Remove the Twitter-link, since that account has not been updated since 2016 (i.e. over seven years ago).
By being less specific about which *exact* JavaScript features are required for the default vs `legacy` build, we don't need to worry about keeping multiple README files up-to-date.
These README files will now refer back to the FAQ for current browser/environment support information.
The [official Chrome extension](https://chrome.google.com/webstore/detail/pdf-viewer/oemmndcbldboiebfnladdacbdfmadadm) has unfortunately not been updated for *three years*, which means that it's currently missing out on years worth of bug fixes, performance improvements, and new features.
In particular, the Chrome extension suffers from a known bug with non-embedded standard fonts; see issue 13669 for details.
For the time being, this patch proposes that we *temporary* make the following changes:
- Remove the mention of the official Chrome extension from the main README, since it seems unfortunate to somewhat prominently recommend users an old and partially non-working extension.
- Don't run the `gulp lint-chromium` task as part of the CI, since in addition to the official extension not having been updated its code is also not being actively maintained.[1]
Once the official Chrome extension has been updated, and it's being actively maintained again, this patch should be simple enough to revert.
---
[1] The last commits, which aren't e.g. linting or general code-maintenance related, happened a year ago now.
Currently we simply use the Babel `preset-env` in the `legacy`-builds of the PDF.js library. This has the side-effect of transpiling the code for *very old* browsers/environments, including ones that we (since many years) no longer support which unnecessarily bloats the size of the `legacy`-builds.
For the CSS files we're only targeting *the supported browsers*, and it's thus possible to extend that to also apply to Babel.
One of the most significant changes, with this patch, is that we'll no longer polyfill `async`/`await` in the `legacy`-builds. However, this shouldn't be an issue given the browsers that we currently support in PDF.js; please refer to:
- https://github.com/mozilla/pdf.js/wiki/Frequently-Asked-Questions#faq-support
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function#browser_compatibility
According to the MDN compatibility data, see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#browser_compatibility, all browsers that we support have native `ReadableStream` implementations (since quite some time too).
Hence only Node.js is now lagging behind w.r.t. `ReadableStream` support, and its experimental implementation doesn't really help us given the life-span of the LTS releases (see https://en.wikipedia.org/wiki/Node.js#Releases).
It seems quite unfortunate to bundle a `ReadableStream` polyfill in the `legacy` builds when it's unnecessary in browsers, given its overall size, but fortunately we can avoid that by simply listing `web-streams-polyfill` as a dependency for the `pdfjs-dist` library.
With ESLint 8 we should now finally be able to start using modern `class` features, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields
However, while both ESLint and Acorn now support this, it unfortunately turns out that Escodegen (which we use during building) still lack the necessary support. Looking at https://github.com/estools/escodegen there's not been any updates since last year, and there's also open PRs adding support for these new `class` features.
To avoid blocking usage of these `class` features in the PDF.js code-base, in particular *private* fields/methods, this patch thus proposes that we (hopefully temporarily) switch to an `escodegen` fork that has the necessary support; please see https://www.npmjs.com/package/@javascript-obfuscator/escodegen
While I have no reason to doubt the security of the `escodegen` fork, this patch nonetheless pins the version number. Furthermore, I've also diffed the output of the two `.js`-files in this forked package against the original files without finding anything that looks immediately "dangerous".
This adds "optional chaining" and "nullish coalescing" to the list of features needed when using the *modern*, i.e. non-translated/non-polyfilled, build of the PDF.js library.
- Don't explicitly mention "ES5" in https://mozilla.github.io/pdf.js/getting_started/#download, since that's no longer accurate. As-is, this will more than likely give users the wrong impression regarding our *actual* browser support.
- Reword the "Getting the Code"-section of the README, since an ES6-compatible browser is no longer sufficient for development purposes given our usage of modern ECMAScript features.
- Update the "Building PDF.js"-section of the README, to explicitly mention both the `gulp generic` and `gulp generic-es5` commands.
Hopefully this will help reduce *some* user confusion, but we should perhaps also consider changing the "-es5"-suffix in our build-scripts and build-folders. (That would however require coming up with a "better" suffix, which might not be trivial.)
- Since the Gitpod contributing work-flow is, from the PDF.js project perspective, completely unsupported we don't want to mention it in such a highly visible way as the README file.
- Since Gitpod is a commercial service, we probably want to avoid *potentially* being seen as advertising and/or endorsing it by mentioning it (somewhat prominently) in the PDF.js README file.
- By leaving the actual Gitpod files in the repository, for now, this should thus avoid outright breaking things for any existing users.
The `git` protocol is unencrypted which means other parties could potentially eavesdrop your traffic. `https` or `ssh` is often encouraged because of this. (For example, the Ruby package manager `bundler` prints a warning when `git` sources are being used.)
At this point in time, trying to keep the development addon compatible with prior Firefox versions is already quite difficult and will become even harder very soon.
Please keep in mind that since Firefox 57, only WebExtensions are allowed/possible to install. The only exceptions are Firefox Nightly, with the `xpinstall.signatures.required` preference[1] set to `false`, and the (as of this writing) current ESR release.[2]
With the current compatibility situation, we thus need to effectively support both Nightly *and* ESR in the addon, while trying to keep up with current/upcoming changes in `mozilla-central`. With old addons no longer being officially supported, the amount of old code being removed/refactored is now increasing quite quickly.
*Please note:* The changes proposed here was to a large extent prompted by bugs such as:
- https://bugzilla.mozilla.org/show_bug.cgi?id=1431533 (already landed)
- https://bugzilla.mozilla.org/show_bug.cgi?id=767640 (already landed)
- https://bugzilla.mozilla.org/show_bug.cgi?id=1432992 (still open)
Upstreaming all of those changes for the `MOZCENTRAL` version of PDF.js, while also keeping the Firefox addon running in older versions of the browser, would quickly become non-trivial.
Since we're using the ruleset from `eslint-plugin-mozilla` for the addon files, which is enforced in `mozilla-central`, we must ensure that the neccessary changes are upstreamed to the PDF.js repo such that the `mozilla-central` version of PDF.js can still be updated without failures.
Trying to feature detect, for the `FIREFOX` build target, some of the changes in the referenced bugs would probably become both quite messy and (not to mention) difficult. E.g. with the upcoming and automatically defined `Cc, Ci, Cu, Cr` variables, any sort of feature detection might be tricky since those need to be defined in the global scope of the files in question.
Finally, given the amount of effort that we'd now need to spend to even attempt to keep the Firefox addon compatible, I just don't think it's worth the effort any more. Especially since the number of people that have, thus far, been doing this work is *very* low and those resources would be better spend elsewhere.
Unfortunately, this probably means that the development addon will no longer be compatible with release versions of Seamonkey. However the README has already mentioned, for quite some time, that support isn't guaranteed.
*In closing:* For all of the reasons mentioned above, I thus propose that we reduce the maintenance burden of the Firefox addon by only supporting the current Firefox Nightly.
---
[1] While the preference exists, and can be toggled, its value is ignored in non-Nightly versions of Firefox.
[2] There's unbranded builds of e.g. the release/beta versions of Firefox, where old and non-WebExtensions addons can be installed. However those builds can probably be assumed to be officially unsupported, and thus not recommended for users.
The https://github.com/mozilla/pdf.js/wiki/Contributing article has been updated to explicitly mention that an ES6 browser is now a minimum requirement for development.
Since we recently have seen a couple of issues filed which seemed to indicate that people tried to use PDF.js in browsers without full ES6 support, it's probably a good idea to mention this more prominently in the README as well.
To reduced the amount of compatibility code that we need to maintain in the addon, I think that we should be more explicit about which Firefox versions we intend to support. In the future, this should allow us to more quickly remove old compatibility code.
Furthermore, this patch also tries to be more explicit about the addon support for Seamonkey, by defining it in terms of the underlying Firefox version.
The Chrome extension is stable and has been around for a few years, so
the ancient note about the extension being experimental can be removed.
Also be a bit more specific about who maintains the Chrome extension,
to make it easier for external contributors to find who is responsible
for the development and maintenance of the PDF.js Chrome extension.
