Build, test and contribute

ShellCanvas builds from source with two toolchains — Node for the interface, Rust for the native core — and one command that checks the contracts between them. This page gets you from a clone to a change you can defend.

Prerequisites

• Git, and a clone of github.com/techartdev/ShellCanvas.
• Node.js with npm, matching the version the repository's package.json declares.
• A stable Rust toolchain, with rustfmt and clippy installed.
• Tauri 2 platform prerequisites. On Windows that means the MSVC build tools and the WebView2 runtime, which recent Windows installs already have.
• Optional: a disposable remote host. Anything you point a probe at should be explicitly authorised and expendable — never a machine that matters.

Windows is the validated development platform. Other hosts compile, but their results are not verified.

Steps

1. Install dependencies exactly. Run npm ci rather than npm install: it installs what the lockfile pins, which is what the checks assume.

2. Run the contract checks. npm run verify is the gate for almost every change — formatting, linting, type checking, unit tests and the contract checks between the interface and the core. Run it before you push, not after review asks you to.

3. Include the native build when you touch Rust. Adding -- --native to that command also builds the current platform's debug executable. It takes noticeably longer, and it is the step that catches a change which type-checks but does not compile.

4. Work on the Rust side directly when iterating. Format with cargo fmt, lint with cargo clippy, and run the crate tests with cargo test, all against the locked dependency set. Formatting is not optional — an unformatted commit fails the checks later, at the least convenient moment.

5. Run the app. The Tauri dev task starts the desktop against your working tree. To work on the interface without hardware, the browser preview runs on fixtures — synthetic by design, and never a stand-in for a real connection.

6. Verify an SDK change against its own harness. The repository ships a verifier for each SDK: the app SDK's scaffolds, builds, packs and installs an example app, and the adapter SDK's exports a template, builds it, packs it, validates the package and exercises host interop. They cover the published developer path end to end, which is the only way to catch a break that unit tests cannot see.

7. Submit the change. Keep it focused, explain what you verified and how, and say plainly what you did not verify. The repository's CONTRIBUTING.md is authoritative for branch and review conventions; where it and this page disagree, follow the repository.

Expected result

The verification command passes locally before you open a pull request, and the description states which checks you ran, on which platform, against what. A change that touches the native core has been compiled and tested, not merely type-checked. A change to an SDK has been run through that SDK's verifier.

Claims in commit messages, documentation and release notes stay as narrow as the evidence: a test establishes the case it executes, and a synthetic probe establishes the fixture it drives. Neither establishes general device support, and writing as though they do is the habit that costs a young project the most credibility.

Limitations

Continuous integration builds and publishes Windows installers; it is not a substitute for running the checks locally, and it will not rescue an unformatted or untested commit. Releases are unsigned, and the release process — the version files, the version check script and the tag that triggers the workflow — is documented inside the repository rather than here.

The SDKs are provisional 0.1 prototypes: interfaces can change between 0.1.x releases, and a contract change means updating the verifier and the documentation in the same change, not afterwards. Test hardware is scarce, so a device-specific report from someone willing to test a patch is often worth more than a patch itself.

ShellCanvas is licensed under MPL-2.0, and contributions are accepted under the same licence.

Related guides

• System architecture — the layers a change lands in.
• Trust and isolation model — the invariants not to weaken.
• Report a reproducible issue — the lighter-weight way to help.
• Compatibility and known limitations — what is already known to be missing.