archematics/README.md

# archematics

Browser plugin to uncover lost mathematical treasures on the web.

More details on its features and operation can be found in the
[options page](etc/options.html).

### Installing archematics

Currently archematics may only be installed as a "development" plugin;
although it is fully implemented and uses only well-known standard
packages, publication policies of the various browsers will require some
changes before it can receive approval as a plugin that can be installed
normally. (For example, Firefox requires that all files in a plugin be
under 4MB, but one of the packages this depends on is only distributed with
files larger than that.) Therefore, to install it, you must:

First, create a distribution directory by either

* the build process below, in which case you are looking for the subdirectory
  named "archematics" of the top-level directory of the repository, or
* or, if you have a link to a zip file of a distribution directory (perhaps
  one was given to you), download the zip file and unzip it into the directory
  of your choice.

How you then install archematics as a development plugin depends on the
browser:

* **Firefox:** open a new tab and enter "about:debugging" in the URL bar.
  Then click the "This Firefox" entry in the left column. Near the top right
  you will see a "Load Temporary Add-on" button. Click this button and
  navigate to the "manifest.json" file in your distribution directory in the
  resulting file browser. Select that file and the plugin will load. Then
  select the "Add-ons and Themes" item in the main Firefox menu and make sure
  the archematics plugin is enabled, and on its preferences tab the parts
  of it you want to use are activated. Then you can navigate to a web page
  where it applies. You will have to give it permission to run on that
  domain (using the "puzzle-piece" plug-in icon at the top right), and then
  reload the page and you should see it take effect.

  Note in Firefox, each time you quit and restart the browser you will need
  to reinstall the extension if you want to use it (since it is only loaded
  as a development extension).

* **Chrome:** open a new tab and enter "chrome://extensions" in the URL bar.
  In the top right-hand corner, enable "Developer mode". Then click on the
  "Load unpacked" button at the top left. Navigate to the distribution
  directory in the resulting file browser, and click on Select. Once the
  extension is loaded, click on the "Details" button. About halfway down the
  page under "Site access" you can give archematics permission to work
  with the sites you want; and most of the way down the page click on\
  "Extension options" to make sure the features you want are enabled.

  In Chrome, the extension should remain installed for future browsing
  sessions as well, even when you stop and restart the browser.

* **Edge:** open a new tab and enter "edge://extensions" in the URL bar.
  On the left side near the bottom, activate "Developer Mode." Click on the
  "Load unpacked" button, and proceed as for Chrome.

* For other browsers, check the browser's documentation for how to load a
  tempory or unpacked extension; we'd be happy to include the procedures
  here if you let us know what worked for you. You can contact the
  developers by email at
    glen at archematics dot app

Enjoy seeing math treasures on the web in a whole old-that-is-new-again way!

### Building archematics

1) Install node v20 or later and pnpm v8.11 or later in your build environment
2) Clone the repository https://code.studioinfinity.org/glen/archematics.git
   and enter its top-level directory
3) Execute `pnpm install`
4) Execute `pnpm build`