Canary

Canary is a post-structuralist graphical user interface (GUI) framework that uses standardized message-passing protocols to represent UI state instead of a typical DOM-based GUI workflow.

Canary scripts (executed as WebAssembly) implement all of the rendering and layout of the GUIs, so the host has little to no involvement in their appearance. This allows virtually unlimited customization of Canary GUIs, as scripts can be reloaded by applications with no impact on application behavior.

Canary's development has been documented on Tebibyte Media's blog: https://tebibyte.media/blog/project/canary/

Screenshots

A screenshot of the Canary sandbox and Sword Art Online script.

A screenshot of the desktop music player controller using the Sword Art Online script.

Using canary-rs

This repository (canary-rs) is the reference implementation for Canary. It is written in Rust, and is licensed under the LGPLv3.

canary-rs is the central hub for Canary's development. It includes host-side Rust code, helper crates for Canary hosts, wrapper crates for scripts authored in Rust, and the documentation that you're currently reading.

canary-rs provides a graphical "sandbox" that embeds the Canary runtime into a lightweight graphical app. It has two purposes: first, to give script authors a playground independent of a larger framework to safely debug, benchmark, and experiment with their scripts, and second, to give Canary embedders a live, functioning example of how Canary can be integrated into their applications.

Running the canary-rs sandbox

The sandbox requires a Canary script to run. If you don't already have one, you can follow these instructions to build the example script provided by canary-rs.

Building the sandbox

To build the sandbox from source, first make sure that you have installed the standard Rust toolchain, including rustup, rustc, and cargo, as well as a frontend to Git. This guide assumes that you are using the Git command-line interface (CLI).

Next, clone the upstream repository:

$ git clone https://git.tebibyte.media/canary/canary-rs.git
$ cd canary-rs

Then, run cargo to build the sandbox package:

$ cargo build --release -p canary_sandbox

Now, the sandbox can be ran with a script:

$ cargo run --release -p canary_sandbox -- <path-to-script>

Running Magpie

(Optional) Building the Sword Art Online demonstration UI script

canary-rs provides an example of a fully-functioning script which, optionally, can be built and loaded into the sandbox to ensure its functioning.

To build it, you must first follow the instructions above to clone and build the sandbox and to set up the Rust toolchain.

Then, add the wasm32-unknown-unknown target so that Rust can compile to WebAssembly:

$ rustup target add wasm32-unknown-unknown

Next, compile the example script:

$ cargo build --release -p sao-ui-rs --target wasm32-unknown-unknown

The path to the built example script is target/wasm32-unknown-unknown/release/sao_ui_rs.wasm. Now it can be run using the sandbox:

$ cargo run --release -p canary_sandbox -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm

Using canary-rs as a Rust library

WARNING: canary-rs is still in alpha development so both its API and its version number are unstable. It is not recommended to use it in your own projects unless you are involved with Canary's development.

canary-rs is not yet available on crates.io, so to add it as a dependency, you must add its upstream git repository instead:

[dependencies]
canary = { git = "https://git.tebibyte.media/canary/canary-rs", rev = "deadbeef" }

Because canary-rs is still under active development, it is recommended to pull a fixed, specific commit using the rev key. That can be a specific tag, some point in the commit history, or whatever the latest commit on main is.

Tebibyte Media is not capable of hosting rustdocs yet, so to learn how the API works, you can read the source code for the test harness, or dig through the source code itself.