Choicelab

Choicelab is a desktop app that lets writers and multimedia designers create rich branching narrative stories on their computer, then publish them on the web, where they'll play on any device or screen. This, here, is the source code to the app. You found it!

Under the hood, Choicelab uses Tauri, a framework for building cross-platform apps. It's sort of like Electron, in that the UI is typically written in HTML, CSS, and JavaScript — but because Tauri uses the system's native webview for rendering, the generated apps are much faster and much smaller.

The frontend is written in TypeScript, with Preact as a UI framework and Vite as a build tool. The backend handles basic setup, file management, and windowing, and is written in Rust like Tauri itself (with a sprinkle of Swift to polyfill functionality Tauri doesn't have yet).

A pre-built alpha version of the app is available for both Mac and Windows.

Setup

Development requires macOS 13.5 and newer, or Windows 10 (version 22H2) and 11:

1. Follow Tauri's guide for setup on macOS — you can use their "Only developing for desktop targets" aside to speed things up — or setup on Windows. Then, continue reading there to install Rust and Node.js.
2. Install Bun; you can run bun to see if you already have it installed.
3. Install Git, if you don't have it already. Any installation method should work.
4. If you're using Windows on ARM, two extra tools are required:
   • In the Visual Studio installer, go to Modify -> Individual Components, and select "MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)".
   • Install LLVM for Windows on ARM — download the woa64 installer and select "Add LLVM to the system PATH" during setup. This is required by the ring cryptography crate, which MSVC alone can't compile on ARM64.

From this repo, install dependencies with bun install-all. Then, run bun keygen to generate a key for deploying automatic updates. (It's recommended that you leave the password field blank.)

Development

Once you're in the repo, run:

• bun install-all to install all dependencies for Rust + Node
• bun dev to run the app locally

Updating the branching logic vocabulary

Choicelab embeds a small word vector (based on GloVe) of common English words found in story questions and input choices (vocab.json). This enables the ability for Choicelab to automatically generate variables and branch stems for authors.

The GloVe-powered word list is committed to this repo; it only needs to be changed if the target words in classifyInputLabel.ts change. To update the list, delete the existing vocab.json, then run bun run gen-vocab to download the full GloVe vector and regenerate the list.

Building

You can run bun build to build a copy of the app locally, which is fine for your own testing purposes and to make sure the app runs. However, this build won't be notarized, so on macOS, you can't run it on another Mac unless you disable that Mac's Gatekeeper (which isn't acceptable for testing on other people's machines).

To avoid having to re-notarize the app manually each time, this repo uses the Tauri GitHub action. Each time there's a push to the release branch, the action will automatically build the app, send it to Apple for notarization (using credentials from Austin's Apple Developer account), and if approved, draft a release on GitHub that's ready for you to publish.

If you need fresh Apple Developer credentials, you'll add them as secret keys to this repo. See the Tauri action docs (above) for more.

Deploying

Deploying automatic app updates requires creating a Tauri private key, then associating it with the choicelab-app repo on GitHub. See Tauri's updater docs for more info.

Once you successfully build the app (using the process above):

1. From GitHub, go to the Releases page in the choicelab-releases repo.
2. Verify the release assets are correct, then publish it.
3. Take the latest.json file, and upload it to the releases.choicelab.xyz S3 bucket, in the /latest subdirectory.
   • This bucket is owned by Austin's AWS account. Talk to them for the access key.

Important: Amazon S3 caches its resources, so the S3-mirroring CloudFront URL that the app checks for updates — releases.choicelab.xyz/latest/latest.json — doesn't always immediately show the latest JSON. You can force S3 to clear its cache by going to CloudFront in AWS, and creating an invalidation.

License

The Choicelab editor (everything outside of src/player/) is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.

The Choicelab player (src/player/) is licensed under the MIT License. This means you can embed the player in your own projects — including commercial or proprietary ones — without GPL obligations. See src/player/LICENSE for details.