Singular in Browser

This repository contains the browser/WebAssembly build support and web interface for running Singular in a user's browser sandbox. Try here:

https://singular-in-browser.pages.dev

The code builds on PR #1360 (and preserves the respective commits).

Repo

Tracked:

• Emscripten build scripts
• browser frontend sources in web-workbench/public
• worker sources, deployment examples, and documentation
• placeholders such as web-workbench/public/engine/README.md.

Not tracked:

• Singular.js
• Singular.wasm
• Singular.data
• generated engine manifests
• release zip and dist/
• local Singular checkouts and dependency build trees.

The CI stores build output as workflow artifacts. Pull requests, daily scheduled builds, and ordinary manual builds are unsigned and read-only. Published releases attach the zip, manifest, and signature as GitHub Release assets.

Building In CI

Implemented in .github/workflows/build.yml:

1. checks out this repository
2. checks out Singular/Singular at the selected ref, default is spielwiese
3. overlays this repo into Singular/emscripten
4. builds the WebAssembly engine and runs its coefficient tests under Node.js
5. packages unsigned CI builds directly
6. for releases, passes only the built public files to a fresh signing job
7. uploads a full release bundle and a deploy artifact.

To create an actual release from Actions, run the workflow on the default main branch, use a new release_id of the form Singular-YYYY-MM-DD (or Singular-YYYY-MM-DD-N), enable create_release, and confirm the trusted branch prompt. The workflow builds and signs the release, creates a draft, uploads its assets, publishes the immutable signed manifest to gh-pages, and only then publishes the GitHub Release. If a later step fails after draft creation, the release remains a recoverable draft. Release ids and manifests are immutable. If the manifest was already published, verify and publish the existing draft manually or use a new release id; never rebuild different bytes under the same id. If no manifest was published, the failed draft and tag may be deleted before requesting a clean rebuild.

The existing GitHub UI flow remains supported: publishing a release with a valid tag triggers the same signed build and attaches its assets. This legacy path starts after the release is public and therefore requires release assets to remain editable; use the draft-first Actions path if immutable GitHub Releases are enabled. Creating a GitHub Release does not deploy files to the Singular webserver; deployment is a separate maintainer operation.

For GitHub Releases, the workflow signs the release manifest and attaches the deploy zips plus manifest files to the GitHub Release. The repository secrets have to be configured before publishing signed releases:

SINGULAR_WASM_RELEASE_PRIVATE_KEY_PEM
SINGULAR_WASM_RELEASE_PUBLIC_KEY_PEM

Pull-request builds do not need signing secrets and should remain read-only. Scheduled builds are also unsigned and cannot create releases or update gh-pages. The build job never receives a signing key. Signed tests and actual releases may only be dispatched from main with Singular/Singular fixed to the trusted spielwiese branch; a separate job checks out the trusted packaging code, signs the built public files, verifies the signature, and removes the private-key file before uploading artifacts.

Local Serving for Tests

After web-workbench/public/engine/ and web-workbench/public/vendor/ are populated:

bash run-web-workbench.sh

open

http://127.0.0.1:9999/

The local server sends the COOP/COEP headers required for SharedArrayBuffer.

Deployment

The Singular webserver should serve immutable release directories, for example:

https://www.singular.uni-kl.de/wasm/releases/2026-06-04/

Manual deployment from the deploy artifact is:

1. download deploy-<release>.zip, or the deploy-<release> workflow artifact
2. upload or unpack the zip on the static hosting provider.

Manual deployment to a normal static webserver is:

1. download singular-workbench-<release>.zip
2. unpack it into a new immutable release directory on the Singular webserver
3. make sure the webserver sends the headers from web-workbench/deploy/nginx.conf
4. keep old release directories immutable
5. optionally update a latest redirect after verification.

Detailed signing and deployment instructions are in web-workbench/docs/DEPLOYMENT.md.