KES 4.0.0: mbin compatibility and add-on overhaul

KES 4.0.0: mbin compatibility

This is a significant version upgrade which overhauls the vast majority of existing KES add-ons, as well as introduces some new API features.
In this update, we have aimed for 100% compatibility of add-ons with the mbin framework to ensure that each feature behaves in a predictable fashion on both kbin and mbin.

If you had previously asked about a particular add-on supporting mbin and had been told that mbin was not supported at that time, or if you had tried KES on an mbin instance and found the results less than satisfactory, now would be a good time to try again.
We have done a top-down audit of every add-on and refactored a large number of them. Special thanks to @Pamasich for considerable help in auditing and bug fixing.

Pamasich has emerged as a contributor with a flair for add-ons that fix existing kbin functionality in a natural and seamless way.

Included in this raft of compatiblity updates were cosmetic fixes to the KES menu on mbin, which was inheriting mbin style settings and causing some elements to appear transparent or misshapen.

If you still encounter bugs or visual anomalies on mbin, please drop a message.

Lastly, this release brings a few new adds-on that introduce fixes or connecting glue, as well as several API changes under the hood geared at future maintainability. Add-on authors are now able to specify other add-ons as dependencies, creating synergistic behavior between add-ons.

Add-ons

Unsanitize Magazine CSS (@Pamasich)

Location: Fixes > Unsanitize Magazine CSS

kbin currently allows magazines to declare custom CSS that is applied while viewing them, and users can also change the CSS of the site in their settings.
Any CSS defined this way gets HTML escaped, causing certain characters like > and & to be replaced with HTML escape codes. This causes any CSS rule that uses them to not actually work, causing confusion and imposing unnecessary limitations on what can be achieved.

This add-on unsanitizes custom CSS on magazine pages to restore functionality of custom styles. This fix is mainly intended as connecting glue for future add-ons that want to check the custom style tags of a magazine.

Fix broken pagination (@Pamasich)

Location: Fixes > Fix broken pagination

This add-on fixes broken pagination arrows when navigating between pages by restoring the intended functionality to the back/forward buttons.

Some pages, such as the All Content view and profile pages, erroneously disable the previous page button, and the next page button always links to the second page.
This causes the pagination to go out of alignment and not respect the page the user is actually on.

This add-on fixes the behavior and makes them act as intended.

Changes

• Code syntax highlighting: now treats "Repair codeblocks" as a necessary dependency, so the act of turning on "Code syntax highlighting" will perforce turn on "Repair codeblocks"

• Repair codeblocks: now treats "Code syntax highlighting" as dependent, so the act of turning off "Repair codeblocks" will perforce turn off "Code syntax highlighting"

• Move federation warning to sidebar: updated this add-on to also support federation warnings on profile pages for users from non-local instances

• Mail label

This add-on was split into two, with the new "Add submission prefix" add-on being newly introduced. The "Add submission prefix" add-on also fixes an issue where the label would appear next to crossposted
submissions, which already have their own label. Prior to this fix, crossposts would look like crossposted by submitted by <username>.

If you had previously set a custom submission prefix in the "Mail label" add-on, you will have to enable the "Add submission prefix" (Location: Threads > Add submission prefix) and set a custom label there.

The "Mail label" add-on is now solely responsible for setting a mail icon/label.

• Resize text:

The add-on now attempts to parse the current point size of elements on the page, rather than defaulting to 14pt. With the old method, enabling this add-on would cause every element on the page to revert to 14pt font, which had a jarring appearance and required the user to bump everything back up to the original size before making changes.

Now the add-on will attempt to start with the current size of the element on the page (where applicable), making toggling the font size up or down feel more natural, since changes are relative to the current size.

In addition, the add-on now gracefully toggles off without needing to reload the page.

Fixes

• All existing add-ons audited or overhauled for compatibility with mbin (list omitted for brevity)
• Releasing a click action on the KES sidebar while multiple pages were highlighted could break the menu
• GitHub's redirection and caching mechanism could cause the contents of the KES menu to appear garbled
• Add mail: fixed an issue where mail links would appear next to your own username
• Clarify recipient: recipient label now appears on the direct message page, not only the inbox reply page
• Code syntax highlighting: restored a missing divider line between the header and code block
• Code syntax highlighting: an unintended interaction with the "Collapsible comments" add-on was causing header icons to be unclickable
• Hover indicator: fixed an issue where the indicator would not appear unless the add-on's color field had been explicitly interacted with before
• Magazine instance names: disabling this add-on would remove checkmarks created by the "Checkmark on subbed mags" add-on
• Notification panel: fixed an issue where settings applied to the panel would sometimes leak into other menus
• Report bug button: this add-on now also applies to the original post in a thread, but not on crossposts

API

• Added the keys depends_on and depends_off to manifest logic

It is now possible for add-ons to depend on other add-ons, or to list add-ons as dependent on them.

This is useful if an add-on requires some fix or functionality from another add-on and expects it to be loaded prior to doing its own work.

For example, the add-on Code syntax highlighting now necessarily depends on the add-on Repair codeblocks, since the former expects code blocks to be sanitized before applying any transformations. Turning Code syntax highlighting on will also turn Repair codeblocks on.
By extension, depends_off specifies add-ons that are dependent on the calling add-on, and which must be switched off if the parent add-on is to be switched off.

When Repair codeblocks is turned off, it necessarily turns off Code syntax highlighting, since the latter depends on the former. However, turning off Code syntax highlighting does not in itself turn off Repair codeblocks.

depends_on and depends_off define arrays of add-on entrypoint names that should be called in sequential order prior to an add-on doing its own setup. This allows for synergistic behavior between multiple add-ons.

• Consolidated add-ons into a global funcs.js file to reduce repository queries

KES now packs over 40 add-ons. At the time of its inception, it was thought that it would be more maintainable to load each sub-script as a remote resource in order to keep them separated. However, as we near the ceiling of the repository rate limit, this approach is becoming untenable due to the need to make so many queries just to load resources. Instead, since the atomic add-ons are already compartmentalized in their own directories at the source code level, this new approach opts to concatenate those into a single functions file that KES loads at runtime. This effectively reduces the queries to the remote to one (plus some additional queries for resources like stylesheets and manifests).

As a result of this change, it is mandatory for add-ons to encapsulate all of their logic within a private function. The KES build tools are then responsible for consolidating these functions and giving them qualified entrypoints based on the original directory hierarchy. This process is automatic.

• Added ephemeral gist generator prototype

This is a shell script aimed at facilitating local testing by developers/maintainers. It uses GitHub fine-grained personal access tokens to create a remote copy of KES inclusive of local changes made to functions and then copies the updated version of KES, with the temporary URL to the new resources, to the clipboard or to stdout. Essentially, this provides a turnkey way of rapidly prototyping local changes without having to update all of the Greasemonkey headers or dealing with additional complications like a local server.

• Added KES internal function getComputedFontSize() to retrieve rendered point size from element IDs

Previously, add-ons using a number field could opt to set an initial value as a fallback. For example, the Change font size add-on used this to set the default point size to 14pt.

With this new logic, it is possible to specify an element's unique selector as an initial value at the JSON manifest level. If the element exists on the page, its point size will be interpolated as the initial value to the number field when the menu in KES is set up. In general, this should provide a more robust and accurate way of setting fallback font sizes that are not hardcoded by literal point size, but rather respect the page's current settings.

Add-ons initializing number fields will automatically make use of this function. Whether you set up a number field with an integer, floating point, or stringwise (element name) value, KES will return the appropriate size.

In the near future, this function will itself be abstracted to the global utility functions file and made available as a helper function that returns the current point size of a particular element on the page, which could be used as part of some add-on's logic.

• Added global utility function getInstanceName()

As part of extending compatibility for mbin, this helper function can be used by add-ons to quickly determine whether the target instance is of type mbin or kbin (string), and take some action accordingly.

Add-ons must now have some explicit handling for mbin (whether this means taking no action or taking some alternate action) to prevent undefined behavior.

Finally, the API reference and documentation have been updated to reflect the above changes.