Mantle Open the web app

Building and testing

Everything is built, run and tested through mk, a small Go program in tools/mk. This page lists the toolchains Mantle needs, every mk command and what it does, where the outputs go, the build tags and environment variables, and what the tests run. Making a release and the hosting are on Releasing and hosting.

Run mk from inside the repository:

go run ./tools/mk <command>

It finds the repository root by looking for tools/mk and go.mod above the current folder.

Toolchains

Tool Version Notes
Go 1.26 or newer (go and toolchain in go.mod) If your Go is older, Go fetches the named toolchain itself. Nothing is installed globally.
Node.js 22 or newer (engines in frontend/package.json) mk runs Vite, Storybook and Vitest through node.
npm The one that comes with Node mk runs npm ci.
Git Any The Android build counts commits for the app's version. Without Git, the version is 0.1.1.
Supabase CLI Pinned in tools/mk/supabase.go Only for this computer's Together service (mk supabase). mk fetches it from its release into out/tools/ the first time, and keeps it only if its SHA-256 is the one pinned.

The exact versions of everything else are in the files, so they are not copied here: Go modules in go.mod and go.sum (Wails, the Lua interpreter, the Windows icon tool, the image and system packages), frontend packages in frontend/package.json and frontend/package-lock.json (Preact, htm, Vite, Storybook, Vitest, Playwright, interactjs, lucide), the Android kit in tools/mk/android.go.

mk installs them for you. It runs npm ci --ignore-scripts --no-audit --no-fund in frontend/ (no package's install script runs, so CI's jobs that hold secrets run none either; the one script in the lock, esbuild's, only checks a binary its platform package already carries) whenever the SHA-256 of package-lock.json differs from the one kept in frontend/node_modules/.mk-lock-sha256.

Per command, you also need:

Command Also needs
package Windows. The desktop app runs on the WebView2 runtime.
android The Android SDK with the NDK, build tools and platform mk pins, and a JDK 17 (see below).
test, icon A Chromium for Playwright. mk test installs one inside frontend/node_modules. mk icon draws with the same one.
supabase A container engine with Docker's API: Docker Desktop, or Podman with its machine started (podman machine init, then podman machine start). The CLI finds Docker's own address; for Podman when Docker Desktop is installed too, set DOCKER_HOST=npipe:////./pipe/podman-machine-default.

A new machine

  1. Git, Go and Node.js (scoop install git go nodejs-lts on Windows), then clone the repository.
  2. go run ./tools/mk dev runs the app, on Windows (the desktop app builds there alone); elsewhere go run ./tools/mk web -serve runs the web build. go run ./tools/mk test runs every test; its first run installs the test browser.
  3. For Mantle Together (the account, devices, watch parties): a container engine (above), then go run ./tools/mk supabase. Builds from source reach this service, and mk test tests it while it runs.
  4. For the Android app: the Android kit (android).

Nothing else is needed to work on Mantle. Releasing and the Together services need what is kept outside the repository: the Android release key's keystore and password, a CodeFloe token that may write the repository, and a Supabase access token (see Releasing). CI has its own copies among the repository's secrets.

Commands

Command What it does
go run ./tools/mk dev Runs the desktop app. Frontend and plugin edits apply live. Go edits rebuild and restart it.
go run ./tools/mk dev -sample The same, with the built-in sample: its profiles, titles and stand-in providers.
go run ./tools/mk package Builds the portable desktop app into out/mantle/.
go run ./tools/mk web Builds the web build, a site of static files, into out/web/.
go run ./tools/mk web -serve The same, then serves it at http://127.0.0.1:8017 to try it.
go run ./tools/mk android Builds the Android app into out/android/mantle.apk.
go run ./tools/mk android -debug The same, with the app debuggable, so its pages can be inspected in Chrome (chrome://inspect).
go run ./tools/mk android -kit Names the Android kit's packages as sdkmanager installs them, one a line.
go run ./tools/mk dist desktop Builds a release's desktop file into out/dist/: mantle-<version>-windows-x64.zip, the portable app.
go run ./tools/mk dist web Builds a release's web file into out/dist/: mantle-<version>-web.zip, the site.
go run ./tools/mk dist android Builds a release's Android file into out/dist/: mantle-<version>-android.apk, signed with the release key.
go run ./tools/mk dist all All three, and SHA256SUMS.txt of them.
go run ./tools/mk release Drafts the release of MANTLE_RELEASE's tag on CodeFloe, with the files dist all made (see Releasing).
go run ./tools/mk release -publish Publishes the drafted release of MANTLE_RELEASE's tag (Pages runs it on the tag, with publish ticked: Releasing).
go run ./tools/mk site Builds the web build of the release HEAD is at and publishes it as the repository's site: a release's at its root, a pre-release's at beta/ (see The site).
go run ./tools/mk backend stable|beta|staging Brings a Together service up to the repository's schema and sign-in settings: production (stable and beta name the same; it says which service first, by name), or staging (production is brought up only once staging has had its migrations: see Channels and their services).
go run ./tools/mk backend [stable|beta|staging] -check Changes nothing, and fails if the service is not the repository's. Without one named, MANTLE_RELEASE's (production's, for a release and a pre-release). -plan is the same but says what would change and fails only if the service cannot be brought up (the workflows report with it).
go run ./tools/mk backend staging -record Records the repository's checksum for each migration staging has had with none recorded (the Supabase CLI's own record): the owner's word that staging ran those files, which production's promotion compares.
go run ./tools/mk backend stable|beta|staging -mail Gives that service its mail service (Resend, from noreply@mantlevid.com; its password in MANTLE_SMTP_PASSWORD) and the repository's emails, and nothing else.
go run ./tools/mk supabase Starts this computer's Together service, the dev channel's (supabase start, leaving out the services the app does not use: Studio and its postgres-meta, Storage, the pooler, the image proxy, the edge functions, and the logs' vector and logflare). See Channels and their services.
go run ./tools/mk supabase <args> Runs the pinned Supabase CLI in the repository with those arguments: stop, status, migration up (a migration added), db reset (the schema from scratch, every account gone).
go run ./tools/mk service check [stable|staging] Asks the hosted Together services and the site whether they are up, with no secret (the scheduled Service workflow runs it; see The Together service).
go run ./tools/mk service usage Reads production's database size and active users (counts only, nothing printed but whether each is below 80% of the Free plan's limit) and whether staging is paused, with SUPABASE_ACCESS_TOKEN; the Service workflow runs it on main (The Together service).
go run ./tools/mk service counts [-sql] Counts what this computer's service holds (accounts, profiles, records, history, lists); -sql prints the read-only query, to run in a hosted project's SQL editor.
go run ./tools/mk service restore <data.sql> Loads a data dump (supabase db dump --data-only) into this computer's service, once it is reset and empty: a restore drill (The Together service).
go run ./tools/mk wiki Publishes these docs as the repository's wiki (see The wiki).
go run ./tools/mk home Builds the homepage (mantlevid.com: what Mantle is, its downloads and betas, its changelog, these docs) into out/home/ (see The homepage).
go run ./tools/mk home -serve The same, then serves it at http://127.0.0.1:8018, made again as its sources change.
go run ./tools/mk home -publish The same, then publishes it to the homepage's repository (MANTLE_HOME_REPO, over SSH with the deploy key MANTLE_HOME_KEY).
go run ./tools/mk shots Takes the homepage's screenshots of the app as it is, into home/shots/.
go run ./tools/mk test Runs the Go tests and the Storybook stories as tests.
go run ./tools/mk test go Only the Go side.
go run ./tools/mk test stories [project...] Only the frontend's tests, of the vitest projects named (desktop, light, phone, node), or all.
go run ./tools/mk test -since <commit> Only the half that the files changed since the commit can affect (go, stories, or both): what a pull request runs in CI, with its base as the commit. -dry-run says which and runs nothing.
go run ./tools/mk storybook Opens Storybook. Extra arguments go to Storybook.
go run ./tools/mk icon Makes the app's icons from the logo.

dev

  1. Installs the frontend packages if the lock file changed.
  2. Starts the Vite dev server on 127.0.0.1:5173. The port is strict: Vite does not pick another if it is taken.
  3. Builds the app (CGO_ENABLED=0, no tags) into out/dev/mantle.exe and runs it with FRONTEND_DEVSERVER_URL pointing at Vite and MANTLE_PLUGINS pointing at the repository's plugins/ folder.
  4. Watches the Go files, go.mod and go.sum every 400 ms. When one changes, it kills the app, rebuilds and starts it again.

Frontend edits apply through Vite. Plugin Lua files are read from plugins/, checked once a second, and reloaded when they change. If a Go build fails, dev waits for the next Go change.

Closing the app's window ends the session, and so does Ctrl+C.

The dev app keeps its data in out/dev/mantle-data.

dev -sample sets MANTLE_SAMPLE=1. The sample is only in builds without the production tag.

package

Windows only. On another system it stops with "packaging on … isn't set up yet".

  1. Installs the frontend packages if needed.
  2. Builds the frontend into frontend/dist, which the Go program embeds. It empties dist first, except .gitkeep.
  3. Builds out/mantle/mantle.new.exe with -tags production -trimpath -ldflags "-s -w -H windowsgui" for windows/amd64, CGO_ENABLED=0.
  4. Deletes old mantle-previous*.exe files that are not running. Windows allows renaming a running program, so it renames the current mantle.exe to mantle-previous.exe (or mantle-previous-2.exe and so on if that name is taken). The previous build keeps running if it is open.
  5. Renames the new program to mantle.exe and prints its size.

web

  1. Installs the frontend packages if needed.
  2. Builds the core as WebAssembly, GOOS=js GOARCH=wasm with -tags production -trimpath -ldflags "-s -w", into frontend/src/web/mantle.wasm.
  3. Copies the Go runtime's loader, lib/wasm/wasm_exec.js of the Go that built the core, to frontend/src/web/wasm_exec.js. Git ignores both.
  4. Builds the frontend with vite build --mode page --base ./ into out/web/, emptying it first. Mode page starts the core in the page before the app (src/web/core.js), and puts a Content-Security-Policy in the page (vite.config.js). Base ./ makes every address relative, so the site works at any path. The core goes in assets/, named by its content as the other files are.
  5. Prints the site's size. With -serve, it then serves out/web/ at http://127.0.0.1:8017 until Ctrl+C.

mk site builds it the same way and publishes it as the repository's site (see The site).

android

  1. Finds the Android kit (below). It stops with a message if a piece is missing.
  2. Installs the frontend packages if needed, then builds the frontend.
  3. Builds libmantle.so for arm64-v8a and x86_64: Mantle's server (-tags web,production) with GOOS=android, CGO_ENABLED=1 and the NDK's clang for Android 8 (API 26) as the C compiler.
  4. Compiles android/src/app/mantle/*.java with javac (Java 8 source and target, against the platform's android.jar), then runs the JVM tests in android/test (the deep-link checks in Links.java and the key file's format in Secrets.java, on the JDK alone, no framework; a failing check stops the build), then turns the classes into classes.dex with d8.
  5. Compiles android/res and links it with android/AndroidManifest.xml using aapt2. The minimum Android is 26 (Android 8) and the target is 34 (Android 14). With -debug, aapt2 link gets --debug-mode, which makes the app debuggable.
  6. Adds classes.dex and the two libraries to the package, aligns it with zipalign, and signs it with apksigner.

The key is the release key when MANTLE_ANDROID_KEYSTORE names one (see Releasing), else out/android/debug.keystore, made on the first build. A phone updates an app only from one signed with the same key, so a build signed with the debug key cannot update a release, nor the other way round: uninstall one to install the other.

The app's version is the one Go stamps in its library (see Versions). Its version code, which a phone updates by, is the version's numbers two digits each, major then minor and patch, then the pre-release's: beta.N is N and the final release 99. So each beta's code is above the last one's, the release's above all its betas', and every one is above the 3000 that beta.6 and beta.7 shipped with: 0.2.1 is 20199, 0.3.0-beta.8 is 30008, 0.3.0 is 30099. A number too big for its digits (a minor or patch over 99, a beta over 98) or a pre-release that is not beta.N fails the build, rather than running into the next digits. For any other build it is the number of commits (a checkout without its whole history, a shallow one too, fails the build: fetch it whole).

The Android kit. One kit builds the app, pinned in tools/mk/android.go (androidPackages, androidJDK), so a build does not depend on what else a machine has installed. A piece missing, or of another version, stops the build and says what to do: for an SDK package, the sdkmanager package that installs it. go run ./tools/mk android -kit names the packages, and CI installs them from it (release.yml).

Piece Version Where
SDK Any ANDROID_HOME, else ANDROID_SDK_ROOT, else %LOCALAPPDATA%\Android\Sdk on Windows, else ~/Android/Sdk.
NDK 27.1.12297006 ANDROID_NDK_HOME, else <sdk>/ndk/27.1.12297006. Its source.properties must say that version, wherever it is.
Build tools 36.0.0 <sdk>/build-tools/36.0.0, its source.properties saying that version.
Platform android-36 <sdk>/platforms/android-36, its source.properties saying API level 36. The app is built against it and targets Android 14 (34), as Android's own builds compile at or past their target.
JDK 17 JAVA_HOME, else the newest JDK 17 in a jdk-* folder beside the SDK's folder (one installed there). Its release file must say 17. Another version is refused, since javac's output differs between them.

test

Runs these, at once where it can:

  1. go test of ./cmd/mantle and the packages of ./internal/... and ./tools/..., named from go list because ./... would reach into frontend/node_modules. Where CI is not set, the core (./internal/core, most of the Go time) is left out of that run and runs as parts at once, each in a go test -run process of its own with the tests dealt out by name, since they run one after another and set the package's own settings, so t.Parallel is not for them. The parts number half the logical CPUs, at most four and at least one (one on a machine of 2 CPUs or fewer). Where CI is set it is one part, in the same go test as the other packages, so the stories beside it keep the CPU they time their waits against. There is no option to run one part: to run some of the core's tests by hand, name them, as go test -run '^(TestA|TestB)$' ./internal/core. The core's tests write their files without flushing them to the disk (their TestMain turns off durable and secrets.Durable; TestPersist saves with it on): no test cuts the power, and the 66,000 flushes of a run were a quarter of its time on a Windows PC. Their TestMain also sets the collector to run a quarter as often (GC percent 400), since the tests' live data is small and the default made it a quarter of the package's CPU (peak memory 620 MB, not 380 MB). The desktop app's own package (./cmd/mantle) builds for Windows alone, since its window library needs a C compiler and GTK elsewhere, so on another system (CI's Linux) its tests run in its server build instead (go test -tags web ./cmd/mantle), and its desktop build is checked as Windows builds it (go vet -gcflags=all=-N -l ./cmd/mantle with GOOS=windows: vet reads types, not code, so it skips the optimiser, and no other step compiles for Windows to share what it compiled: 15% less time).
  2. go test -tags production -run ^TestProduction ./internal/core ./internal/build. This starts the core as the packaged app does: no sample, the plugins that come with it, and the saved state. (^TestProduction: the other tests that name production, its service, run in step 1.)
  3. go vet -tags web ./cmd/mantle. This checks the Android app's server, which leaves out the desktop's files.
  4. go vet ./cmd/mantle ./internal/... with GOOS=js GOARCH=wasm: the web build.
  5. The web build's own tests (internal/core/*_js_test.go, each named for the browser), built as WebAssembly into out/wasmtest/ and run in Node. Go's own runner (wasm_exec_node.js) cannot open folders on Windows and passes on more of the environment than a WebAssembly program may have, so mk runs them with its own (wasmRunner).
  6. The frontend tests: installs the packages if needed, installs Playwright's headless Chromium into frontend/node_modules (on a Linux CI machine, with the system libraries it needs, at the same time), then runs vitest run in frontend/. Besides the stories, that runs the tests that need no page (src/**/*.test.js: the web build's files, that every phone breakpoint in the styles is the one ui/phone.js says, and how a picture keeps pace with a device, src/app/pace.test.js) in Node, as the node project. node node_modules/vitest/vitest.mjs run --project node runs only those, with no browser. Each browser project runs a page for each core (up to 12), so the three run up to 36 pages at once. The pages come from a Vite server that listens on 127.0.0.1 alone (server.host in vitest.config.js; Vitest 5's --browser.api.host changes nothing). Where CI is not set (a computer someone is using) vitest.config.js caps each project at min(6, cores - 1) pages (six on a PC of 7 cores or more: about a quarter less CPU for the same time on a 16-core PC), and the files that play real media (Player*.stories.js, the longest) start first, by their file names. To run as CI does, set CI for the run ($env:CI = "1" in PowerShell, CI=1 in a POSIX shell): no cap on pages, the stories in vitest's own order, and the core's tests in one process. The stories' waits are for the CPU they get, and on a runner the Go tests share it, so CI has nothing of this that spreads work over more of it. Many tools set CI themselves, so a run that seems to ignore the cap may have it set.

The Go output is printed after the stories', with how long each go command (and each part of the core's tests) took. mk test first says how many CPUs the machine has and Go's GOMAXPROCS, which in a container is its CPU quota and may be fewer than the CPUs it shows. If any part fails, mk test exits with an error.

Together's service tests (internal/together: service_test.go) need a service. While this computer's runs (mk supabase) and no other is named (MANTLE_TOGETHER_URL, MANTLE_TOGETHER), mk test has them test it, with its keys from supabase status. Otherwise they are skipped. After them it runs the checks of the service's database (supabase/checks/*.sql) in this computer's, with psql in its container as its superuser (supabase_admin): SQL that needs what a test through the service's API cannot have, such as a table given the statistics it is checked with. Each runs in a transaction it rolls back, and fails with an error that says what went wrong.

go run ./tools/mk test go runs the Go side alone (steps 1 to 5), and go run ./tools/mk test stories the frontend's alone (step 6), of the vitest projects named after it (all if none), for example go run ./tools/mk test stories phone.

go run ./tools/mk test -since <commit> decides which of the two to run from git diff of the files changed since the commit (from its common ancestor with HEAD, so the history must be there), and says first what it decided and which files decided it (tools/mk/since.go). It errs towards running more, and the rules are:

  • Every file is placed alone. Only the Go side runs when every file is the Go side's: cmd/, internal/, plugins/, android/, supabase/, and Go files at the root (the plugins, the Android app's files and the service's schema are read by Go tests). Only the stories run (all the projects, and the tests in Node) when every file is in frontend/ and is none of those below.
  • Both run for a file read on both sides. In frontend/, the Go tests read src/fixtures/ (they compare them with what the core makes, and go test -update rewrites them; the stories load them), src/styles/themes.json, src/app/keys.js, src/app/languages.json, src/ui/icon.js, index.html, public/manifest.webmanifest, public/favicon.svg, src/brand/ (the homepage's build), and src/web/ (the web build's glue, the other half of the Go code built for the browser). The binary embeds frontend/dist/. And in the Go side, the stories serve internal/sample/art/. A test fails if a Go test names a file in frontend/ that is not on this list (TestSharedFilesAreListed): add what it names.
  • Both run for what changes how the tests run: tools/mk/, .forgejo/, go.mod, go.sum, frontend/package.json and its lock; and for any file these rules do not place (.editorconfig, a new folder at the root). The same when the diff cannot be read, or is empty.
  • docs/, home/, the README and the licence decide nothing: no test reads them dependably (TestMakeHome reads docs/ and home/ but skips unless the frontend's packages are installed, which mk test go does not do), so a pull request of Go and docs runs the Go side. The homepage is built from main as it changes (homepage.yml), so a mistake in a page shows there. Alone they run both, as the workflow's paths-ignore skips a pull request of docs/, the README and the licence alone.

-since takes no go or stories after it. Setting CI=1 as the runner does and running go run ./tools/mk test -since <commit> -dry-run shows what a pull request would run.

CodeFloe runs mk test for a pull request once it is ready (.forgejo/workflows/tests.yml), on its Linux runners, as one job. CI minutes are counted (2,500 a month) and each job pays to start, so it runs no more than it must:

  • A pull request titled WIP: or [WIP] is a draft and runs nothing. Open one as a draft while it is worked on and reviewed, then take WIP: off its title when it is ready: that runs the tests, as does each push after (a newer push cancels the run before it). Forgejo does not say what an edit changed, so any edit of a ready pull request runs them too: describe it while it is a draft.
  • A pull request that changes only docs/, the README or the licence runs nothing.
  • main is not tested again when a pull request merges, nor is a release: main's branch protection takes only a pull request that is up to date with it, so main is then the code that pull request tested, and nobody pushes to it directly. A release tags main's code (release.yml checks). The one thing a push to main runs is Together's service job, and no job for a pull request has a secret (see Releasing).
  • A pull request runs only the half of the tests it can affect, still in one job: go run ./tools/mk test -since <the pull request's base> (the workflow passes github.event.pull_request.base.sha, and checks out the whole history to diff against it), which runs the Go side alone, the stories alone, or both, as above, and says which files decided. Both run for anything it cannot place. The job and its status, Tests / Tests, are the same whatever ran.
  • The runner sets CI, so the layout is the one before the faster local runs: the stories run with no cap on pages and in vitest's order, and the core's tests are one process (see steps 1 and 6).
  • Nothing is cached between runs. Go's build cache was not worth it: setup-go saved it again after every run, half a minute or more, and the Go tests run beside the stories, which take longer. The frontend's packages with the test browser (183 MB) were saved after each run and never restored: a run on another runner, minutes later, found nothing, as the runners' caches are not shared. Setting up takes about 25 s: on a Linux CI machine mk installs the packages, the browser and the system libraries it needs (the headless shell's own list and a few fonts, not the hundred packages of playwright install --with-deps) at once.

The code only Windows builds (the desktop window's, and the tests in internal/secrets of reading a file that DPAPI sealed) is tested on Windows before each release (see Releasing).

Every Storybook story is a test. They run in a headless Chromium, three ways (the projects in frontend/vitest.config.js):

Project Viewport Theme Stories run
desktop Desktop width The default dark theme (graphite) All except those tagged narrow.
light Desktop width The light theme (daylight) Only stories that show something. Those tagged interaction and narrow are left out.
phone Phone width (390 by 844) The default dark theme All except those tagged wide or behaviour.

A story of what only a wide window has (the rail, a menu beside what opened it) is tagged wide. A story of the phone's own interface is tagged narrow. Stories tagged interaction test behaviour. They run with every story but stay out of the docs. A story of the player or the core's logic, which no width changes (hls.js, recovery, pace, a party), is tagged behaviour as well, and runs at desktop width only. So is a page's story of keys, a controller or a form's steps, where nothing is a menu, a dialog, a touch, a scroll or a drag; the phone keeps what shows each page and what differs on it. The phone keeps one story of each state the player shows (Up next, Skip intro, Still there?, the notes) and what differs on it (touch, the sheets).

Every story must also pass shared layout checks, axe (accessibility) and a quiet console. See the Introduction page in Storybook.

The test browser is started with --enable-blink-features=AudioVideoTracks, as the app's WebView is, so audio tracks can be switched. The stories of a file repackaged as HLS (PlayerStreams*.stories.js, with their shared helpers in frontend/src/testkit/repackaged.js) hide them, as the web build and Android have none.

The player's stories keep the dev server out of what they wait on: their films and the core's HLS files are read once, as a story file loads, and played or answered from memory (frontend/src/testkit/player.js), so a loaded machine's slow answers are not what a story waits for. The stories that call fakeMedia (Switch source while playing in PlayerRecovery.stories.js, and in PlayerStreamsRepackaged.stories.js Audio tracks, repackaged and the quiet watch's stories of a restart that keeps the track and speed, a seek or a resume while it hangs, a stall left alone, a stream that played, stopped and was reconnected, a source played, left and picked again, a late switch to hls.js, a source picked or taken over from a played one whose hls.js hangs, and a picture that hangs while another is to take over) are about what the player does, not about what a browser makes of a file, and play on stand-ins for the WebView's media and for hls.js (frontend/src/testkit/media.js): a film loads (or is held back until the story lets it come), seeks, plays, stalls and ends as the story says, a frame at a time, so nothing they wait on depends on how busy the machine is. fakeHls puts itself in libs.hls and puts the real one back as the story ends. The quiet watch's other stories play real hls.js on real films (RepackagedQuiet, RepackagedQuietOnce, RepackagedSlowNotQuiet and ResumeIntoAPartQuiet): they hold the watch's seconds with heldTimers, but the core's slow init segment and what hls.js loads are real time, which they wait on for no more than MEDIA. The stand-ins of media.js are for the player's loading and handover; device.js is for a clock and its frames (the pace stories) and the picture sound's own are for pictureSound.js alone. Some timers of the player's are the story's to move: restClock ends the controls' rest (the story of it plays the sample, with no film to load, play or end), heldTimers runs other timers of a given delay (the 800 ms before a realigning), and skewClock puts the page's clock ahead (a stall, the twenty seconds between realignings, two hours with nobody there). The rest it waits out. A wait is for no more than MEDIA (10 s), except where it is for a timer of the player's that the story does not move, or for playing on to a time: RepackageSlow and RepackageSlowThenDecoded (12 s, the player's wait of 8 s for the core), RepackageFailsThenDecoded (12 s, its re-ask after 2 s), AfterEpisodesInARow (15 s, for Up next's countdown of 10 s) and SoundBeside (up to 30 s for a stretch measured with no stall, hold or seek, though its film's 8 s hold only five to seven tries, a second of it or more each: past its end the sound plays no more, and the wait runs out). Two media elements' clocks are not one: each is kept by its own audio output, a muted one's timed on a thread of the page's, which a busy machine holds up with nothing said, a heard one's by the audio device. So SoundBeside checks what the player sets, the sound's speed its picture's within the nudge (NUDGED) and the sound within SEEK of it, not how far the two clocks move apart over a stretch. A check that nothing happened (a dialog that did not come, a state that did not change) still waits a fixed real time, 100 ms to 2.5 s. Those sleeps are listed by file in frontend/src/testkit/storyWaits.test.js (run in Node with the rest): a story that sleeps for something that happens waits on a time the machine does not keep (CI's runners with other jobs beside, which is where the stories' flakes showed), so a new sleep fails that test until the story has waited on the condition, held the app's timer (heldTimers: fire(n) runs only the oldest n) or used the helpers made for the app's own timing (connectPad's press is one frame down, as the app's poll repeats a control it sees down for 420 ms; mouseButton makes its events together, as the app tells a click from its echo by their time apart), or been added to the list as one that waits out something that cannot be seen. The clock's helpers match the page's timers by length (heldTimers, quicken), and leave the story's own waits as they are: a waitFor or findBy… whose timeout is a length the story quickens or holds still has all of it (the test library's timeout is told from the page's timers by its name, which Testing/Clock checks). A story that measures text (where a scroller ends) first waits for the page's fonts (await document.fonts.ready): until they have loaded (late, on a busy runner) the text is in a system font (on CI's Linux Liberation Sans, which takes other lines), and what was measured moves when they land.

Plugin tests (plugins/*/tests/*.json) run as part of the Go tests. Run only them with go test ./internal/plugin -run TestPlugins. See the plugin author guide.

frontend/measure/closing/closing.mjs measures whether the web build's last save finishes as a tab closes, and how long a save and the files' write batch leave a change unsaved (docs/dev/internals.md, the web build): cd frontend && PLAYWRIGHT_BROWSERS_PATH=0 node measure/closing/closing.mjs 15 (about ten minutes: each scenario is run that many times in the headless Chromium mk test installs, one page at a time; MARSHAL_MS is the stand-in core's marshalling time, 36 ms: a save in WebAssembly, BenchmarkSave). It is not part of mk test.

mk test does not run the race detector: it needs cgo and a C compiler (scoop install mingw), which the build otherwise does without, and CI has no C library to build with. Where code is read and written from several goroutines, run it by hand: go test -race ./internal/container ./internal/core takes about three minutes (cgo is on by itself once a C compiler is on the PATH; if it was turned off, $env:CGO_ENABLED = "1" first). TestPlayableWhileDescribing, TestRepackagedAudioWhileDescribing and TestReadersTakeTheLock are tests for it. Without -race they still check what is said, held and after, that asking does not wait, and that each reader (Playable, Decoded, Codecs, Playlist) waits while the lock is held; TestDescribeWritesUnderLock checks without it that a Matroska track's description is written under the lock. What only -race finds is a write of the MP4 tracks' description outside it, or a reader that takes the lock but reads a field it does not guard.

storybook

Opens Storybook on port 6016 with --exact-port. If it is already running there, mk says so instead of asking. Other arguments go to Storybook. Storybook shows the component library with each component's docs, controls and behaviour stories.

icon

Run it when the logo changes. It draws frontend/src/brand/app-icon.svg with the frontend's Chromium, and writes:

  • cmd/mantle/rsrc_windows_amd64.syso: the Windows icon resource, with sizes from 16 to 256. It is linked into every Windows build.
  • The web build's icons in frontend/public/icons (192, 512, maskable 512 and the Apple touch icon), and frontend/public/favicon.svg.
  • The Android launcher icon's foreground at each density in android/res/mipmap-*, drawn from frontend/src/brand/mark.svg.

All of these are kept in the repository.

Where outputs go

All outputs are in out/, which Git ignores.

Path What
out/dev/ The dev app (mantle.exe) and its mantle-data and Downloads.
out/mantle/ The packaged desktop app: mantle.exe, mantle-previous.exe, and its mantle-data and Downloads when run there.
out/web/ The web build: the site to put on a web host.
out/wasmtest/ The core's tests, built as WebAssembly by mk test.
out/android/ mantle.apk, debug.keystore, and build/ (the work folder, emptied at each build).
out/build/ The desktop app as mk dist desktop builds it, before it is zipped.
out/dist/ A release's files, as mk dist makes them.
out/home/ The homepage, as mk home makes it.
out/shots/ The server build mk shots takes the homepage's screenshots of.
frontend/dist/ The built frontend. The Go program embeds it.

Build tags

Tag Effect
none The desktop app: cmd/mantle/main.go, desktop.go and the Wails window.
web The Android app's server: cmd/mantle/web.go replaces cmd/mantle/main.go. The desktop's files are left out.
production No sample: its stand-in plugins, titles and artwork are left out, and cmd/mantle/devhooks_windows.go is left out. Every packaged build uses it.

The Android library is built with web,production. The web build is GOOS=js GOARCH=wasm (Go's own js constraint): cmd/mantle/main_js.go replaces cmd/mantle/main.go, and internal/core/browser_js.go sets core.InBrowser.

go build of the repository needs frontend/dist to exist (a .gitkeep keeps it there). It is embedded with //go:embed all:frontend/dist (embed_ui.go, at the repository root), except in the web build, whose page is the site itself.

Environment variables

MANTLE_TOGETHER, MANTLE_TOGETHER_URL, MANTLE_TOGETHER_KEY and MANTLE_PLUGINS are development tools: a build with the production tag (every packaged build, and the Android library) does not read them (build.DevEnv, build.Production), so a released app has one behaviour and cannot be pointed at another service or at a folder of plugins by its environment. mk dev, mk test and the docs' screenshots build without the tag. MANTLE_REPLACES (the updater's) and MANTLE_CODE (the server's access code, new) are read by every build.

Variable Used by What it does
FRONTEND_DEVSERVER_URL The dev app Points the app at the Vite dev server for the frontend. Set by mk dev.
MANTLE_TOGETHER=stable|beta|dev|staging The app (not production builds); go test ./internal/together Reaches that channel's Together service (or staging's) instead of its own channel's. The service's tests refuse production, which people use.
MANTLE_TOGETHER_URL, MANTLE_TOGETHER_KEY The app (not production builds); go test ./internal/together Reach another Together service: a Supabase project's address and its publishable key. With MANTLE_TOGETHER_ADMIN, its secret key, the service's tests run against it (they make accounts and delete them after); without, they are skipped.
SUPABASE_ACCESS_TOKEN mk backend A Supabase access token that reaches the channels' projects. CI's staging jobs read SUPABASE_STAGING_ACCESS_TOKEN first, a token that reaches staging alone, if the account has one (releasing).
DOCKER_HOST mk supabase The container engine's address, for the Supabase CLI. Unset, Docker's own.
MANTLE_RELEASE mk dist, mk backend The release's tag (v0.3.0). The commit must be at it, with nothing changed; the files are named for it. Unset, they are a trial's, named dev.
MANTLE_ANDROID_KEYSTORE mk android, mk dist android The release key's keystore. mk dist android needs it.
MANTLE_ANDROID_KEYSTORE_PASSWORD The same The keystore's password. apksigner reads it from the environment, so it is never in a command's arguments.
MANTLE_ANDROID_KEY_ALIAS The same The key's alias in the keystore. mantle if not set.
MANTLE_ANDROID_KEY_PASSWORD The same The key's own password, if it differs from the keystore's.
ANDROID_NDK_HOME mk android Where the pinned NDK (27.1.12297006) is, in place of <sdk>/ndk/27.1.12297006. Unset, or empty, for the SDK's.
MANTLE_PLUGINS The app (not production builds) Read the plugins from this folder instead of the embedded ones, and reload them as they change. Set by mk dev.
MANTLE_SAMPLE=1 The app, non-production builds Starts with the built-in sample. Set by mk dev -sample.
MANTLE_DEV_WINDOW=x,y,w,h Windows dev builds Opens the window there (physical pixels) without ever activating it, so automated checks do not disturb whoever is at the machine.
MANTLE_DEV_CDP=port Windows dev builds Exposes the WebView's DevTools protocol on localhost:port.
ANDROID_HOME, ANDROID_SDK_ROOT, JAVA_HOME mk android Where the kit is.
PLAYWRIGHT_BROWSERS_PATH=0 mk test, mk icon Keeps the test browser inside frontend/node_modules. Set by mk.

The two MANTLE_DEV_ hooks are in cmd/mantle/devhooks_windows.go, which production, web and Android builds leave out.

Versions

Go stamps every build made from the repository with its version, from Git: at a release's tag (v0.3.0), that version; at a commit after one, a pseudo-version of the commit (0.3.1-0.20261023101500-abcdef123456); with uncommitted changes, +dirty after it. Before the first tag, it is 0.0.0-…. The app reads it with internal/build and shows it in the first line of its log, in the User-Agent it asks services with, and in Settings → Data and storage → About. A build Go did not stamp (go run, a test) says dev.

Running the Android app's server from source

The Android app runs Mantle as a server behind an access code (cmd/mantle/web.go, server.Gate). To run that server on a computer while you work, build the frontend once, then run the program with the web tag:

cd frontend
node node_modules/vite/bin/vite.js build
cd ..
go run -tags web . -listen 127.0.0.1:8070 -data out/dev-web

It prints its addresses and the access code. A browser at one of them asks for the code.

Flag Default What it does
-listen 127.0.0.1:8070 Where to serve. 127.0.0.1:8070 is this computer alone. An address on a network (:8070 is every network this computer is on) is refused unless -insecure-lan is also given. The refusal happens before anything is opened.
-insecure-lan off Allows -listen beyond this computer. It is plain HTTP: anyone on those networks can see the access code and everything sent, and can use a session they capture for 30 days. A container needs it too, since it must listen on every address inside it.
-allow-host none A name a browser reaches this server by, beyond the addresses and this computer's own name (for a name on your network, such as nas.lan, or a reverse proxy's public name). Repeat it for more names; give the name without a port.
-proxied off A reverse proxy on this computer fronts the server (see below): the wrong-code limit counts its clients apart, by the last X-Forwarded-For the proxy sends. Only a request from this computer is believed, so a client on a network cannot forge it.
-data mantle-data, beside the program The data folder.
-code The code kept in the data folder, or a new one The access code, 8 to 64 letters or digits. A new code signs every device out. It is on the command line, which other programs on the computer can read: prefer -code-file, or the MANTLE_CODE environment variable (each used when -code is not given, in that order). The server prints the access code as it starts only when it made it: a code given by any of the three is not printed.
-code-file none A file with the access code, as -code.

A browser that reaches the server by another name is answered 421 Misdirected Request, and the page says which name it saw and the flag that lets it in. The names are refused on purpose: a page on another site can be pointed at this address under its own name, and the server then never sees the code. Only the addresses, localhost and this computer's name are answered by default.

A reverse proxy on this same computer (give its public name with -allow-host, and -listen 127.0.0.1:...): its requests reach the server from 127.0.0.1. The /auth?code= link, which puts the code in a URL the proxy may log, therefore signs in only when the Host is a loopback name (127.0.0.1, localhost), never by the proxy's public name; people sign in with the page's form. The wrong-code limit counts one address per client only with -proxied, and then the proxy must send the client's address as the last X-Forwarded-For entry (nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;, Caddy and Traefik do by default). Without -proxied every client of the proxy is one address, and one stranger's wrong codes slow the owner's too. The limit is not lifted for a right code: the code is 8 or more letters or digits, but a guess answered at once is what the limit is there to prevent, so only a separate address can be exempt. A proxy on another computer is not believed (its address is a network's), so use the server on a network address with -insecure-lan for that.

One server is one Mantle: every browser signed in to it shares its profiles, the profile in use and a PIN once given. Switching profile in one browser switches it in the others, and a profile unlocked in one is unlocked in all. On the Android app this is the phone alone.

This page is made from docs/dev/building.md in the repository.