Contributing guide
Contributing
Thanks for helping. Sumi has one maintainer, so here is what gets merged.
Before you start
- Typos, broken links and small bug fixes can go straight to a pull request.
- Anything bigger needs an issue first, and a yes on it. When an issue is open for a pull request, it gets the
help wantedlabel. A large pull request without one will be closed. - Until 1.0, Sumi builds what’s on the roadmap. Ideas outside it are welcome in an issue, and decided case by case.
- How the island looks and moves is set in the design page. A change to a size, a colour, a spring or a timing needs my OK in an issue first.
- To take an issue, say so in a comment and I’ll assign it to you. One person per issue.
- One change per pull request, with no reformatting or renames on the side.
Branches
main is what users get. It only changes when dev is merged for a release.
dev is where work lands. Open your pull request against dev, from a branch named after what it does: feat/media-module, fix/click-through-win10, docs/shortcuts, refactor/rust-cleanups, chore/release-0.5.0.
Pull requests into dev are squash-merged, so the PR title becomes the commit message. Write it as a Conventional Commit: feat: show album art in the island, fix: keep focus on the game when a timer ends.
Setup
You need Windows 10 or 11 with Node.js 24, Rust and the Microsoft C++ Build Tools. From a terminal:
winget install OpenJS.NodeJS.LTS --version 24.22.1winget install Rustlang.Rustupwinget install Microsoft.VisualStudio.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"The exact Rust and Node versions are pinned in rust-toolchain.toml and .node-version; Rust installs the right one on the first build. Windows 10 may also need WebView2.
Then, in the repository:
npm installnpm run tauri devThe island appears at the top of your primary screen. Quit it from the tray icon. Changes to the frontend reload instantly; changes to Rust restart the app.
How the code is laid out
src-tauri/src/lib.rsstarts the app, one copy at a time: the tray icon, the list of commands the page can call, and each module’s watcher.src-tauri/src/tray.rsdraws the tray icon at the taskbar’s size with the corner the page asks for (the microphone or camera dot, or the music), sets its tooltip and its menu’s words, and tucks the island on a left click.src-tauri/src/island.rskeeps the window at the top of the screen, lets clicks through everywhere but the island, closes the panel, and tells the page when a window is dragged and of a click elsewhere while the island waits to tuck itself.src-tauri/src/fullscreen.rshides the island while a game, a video or a slideshow fills the primary screen, and hears a window start and end a move or a resize.src-tauri/src/media.rsreads the players Windows’ media controls can see, and plays, pauses, skips and seeks.src-tauri/src/privacy.rsfinds the apps using the microphone or the camera, and mutes the microphone.src-tauri/src/apps.rsreads Start’s apps, opens the one picked in the command bar, and opens a question in an assistant or the search engine.src-tauri/src/bar.rsregisters the command bar’s shortcut, and gives focus to the bar and back.src-tauri/src/timers.rsplays the timers’ chime. The timers themselves live in the page’s memory only.src-tauri/src/welcome.rskeeps the first-launch welcome’s flag, a file holding the version that said hello.src/Island.sveltedraws the island.src/PrivacyCard.sveltedraws the microphone and camera card and calls theprivacy_mute,privacy_settingsandprivacy_showcommands. Only these two files talk to Rust;src/main.tsandsrc/App.sveltejust mount the island.src/lib/*.tsis the logic without the DOM: who gets the island, sizes, springs, music, privacy, timers (timers.ts), the first-launch welcome (welcome.ts), the tuck and what tucks itself (tuck.ts), what the tray icon shows and says (tray.ts), and what the command bar’s line means (intent.ts). Each file has its Vitest tests beside it (*.test.ts).src/lib/demo.tsplays every state from the keyboard, in a browser without Rust, and runs the site’s live examples (npm run showcase).site/is the website, in Astro and Starlight. Its English contributing page imports this file.
The page calls Rust with invoke() and listens to its events with listen(). Each Rust type has a TypeScript twin: change both together. TypeScript types without a file are written inline in src/Island.svelte.
| Name | Direction | Rust | TypeScript |
|---|---|---|---|
set_island_rects |
page → Rust | rects: Vec<Rect> (island.rs) |
{ x, y, width, height, radius }[] |
set_island_expanded |
page → Rust | expanded: bool |
boolean |
island_presence |
page → Rust | returns Presence (fullscreen.rs), as last decided |
Presence (src/lib/activities.ts) |
set_tray |
page → Rust | tray: Tray (tray.rs): the icon’s corner, its tooltip and its menu’s words |
Tray (src/lib/tray.ts) |
set_island_waiting |
page → Rust | waiting: bool, while the island waits to tuck itself |
boolean |
media_control |
page → Rust | id: String, action: Action (media.rs) |
'play', 'pause', 'next' or 'previous' |
media_seek |
page → Rust | id: String, ms: i64 |
number |
media_players |
page → Rust | returns Snapshot (media.rs) |
{ players: Player[]; artwork: Record<string, string> } |
privacy_state |
page → Rust | returns Privacy (privacy.rs) |
Privacy (src/lib/privacy.ts) |
privacy_mute |
page → Rust | muted: bool |
boolean |
privacy_settings |
page → Rust | camera: bool |
boolean |
privacy_show |
page → Rust | name: String, returns bool |
boolean |
apps_list |
page → Rust | returns Vec<App> (apps.rs) |
{ name: string; id: string }[] |
has_claude |
page → Rust | returns bool |
boolean |
app_icon |
page → Rust | id: String, returns Option<Icon> (privacy.rs) |
{ side, rgba } or null |
app_launch |
page → Rust | id: String, returns bool |
boolean |
assistant_open |
page → Rust | target: Target (apps.rs), query: String, returns bool |
Target (src/lib/intent.ts), string |
bar_shortcut |
page → Rust | returns Option<&str> (bar.rs) |
string or null |
bar_focus |
page → Rust | open: bool |
boolean |
timer_chime |
page → Rust | nothing | nothing |
welcome_pending |
page → Rust | returns bool (welcome.rs) |
boolean |
welcome_done |
page → Rust | returns Result<(), String> |
nothing, or an error |
island://presence |
Rust → page | Presence (fullscreen.rs) |
Presence (src/lib/activities.ts) |
island://pointer |
Rust → page | Option<u32>: the hover time in ms, None when the cursor leaves |
number or null |
island://dismiss |
Rust → page | nothing | nothing |
island://tuck |
Rust → page | nothing: a left click on the tray icon or its menu’s tuck item, which tucks or brings back | nothing |
island://moving |
Rust → page | bool: true once a window is dragged, false when the move ends |
boolean |
island://elsewhere |
Rust → page | nothing: a click outside the island while it waits to tuck itself | nothing |
bar://toggle |
Rust → page | nothing | nothing |
media://players |
Rust → page | Vec<Player> (media.rs) |
Player[] (src/lib/music.ts) |
media://artwork |
Rust → page | json!({ id, url }), with url: Option<String> |
{ id, url }, with url a data: URL or null |
privacy://state |
Rust → page | Privacy (privacy.rs) |
Privacy (src/lib/privacy.ts) |
Before you push
Run what CI runs:
npm run lint && npm run check && npm testnpm run buildcd src-tauri && cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo testTypeScript and Svelte have no formatter: match the surrounding style (single quotes, no semicolons, 2 spaces) and don’t run Prettier.
To try your change as users will get it, build the installer with npm run tauri build.
On your first pull request, CI starts once I approve it. Leave Allow edits by maintainers on, so I can bring your branch up to date.
What I look at in review
- It does one thing, with tests for the logic.
- It fails quietly. If a Windows API call fails, the module hides and the app keeps running. No
unwrap()on Windows calls. - It costs nothing at rest: no timer or animation running when nothing changes.
- It keeps your PC private. Nothing the island shows is written to a log or a file, and nothing leaves the PC unless the user turns that feature on. No telemetry, analytics or crash reports.
- It adds no dependency, network request or Tauri permission (
src-tauri/capabilities/) unless the issue agreed on it. Every package is code that each user runs. - The UI works with reduced motion and keeps AA contrast.
- It reads like the code around it, so the next person, or an AI, can pick it up. Rust:
snake_casefor functions and modules,CamelCasefor types,UPPER_CASEfor constants. TypeScript:camelCase,PascalCasefor types,UPPER_CASEfor shared constants. Svelte components:PascalCase.svelte. Comments are short and say why, not what. - It leaves no debt behind: no dead code and no
TODO. A known limit gets a// shortcut: <the limit>, <when to upgrade>comment. - A new file, command or event gets its line in How the code is laid out, and a new Rust file opens with a
//!comment that says what it does. - Rust:
unsafestays small. A block that relies on something the compiler can’t check (a raw pointer it reads,from_raw, a transmute, a callback’slparam) says why it’s sound in a// SAFETY:comment. A plain Windows call needs none.windowsis for COM, WinRT and a Win32 call that takes or returns awindowstype in that code (HANDLE,PCWSTR,PWSTR);windows-sysfor every other Win32 call, even in the same file. - A change users can see updates its page in the site’s docs, and the README when what users can do changes, in English and French. If you don’t write French, say so and I’ll add it.
- Its words are plain and short: code comments, commit messages, the PR description, and the docs and README in both languages.
AI tools
Use them if they help. You answer for every line: you ran it on Windows, you understand it and you can explain it in review. Pull requests and issues that look generated and untested are closed without review. Coding agents get their rules from AGENTS.md.
Translations
Sumi’s README and site are in English and French. Please don’t open a pull request for another language yet: I can’t review text I can’t read, and every release would need it updated. Open a discussion if you’d like one.
Licence
By sending a pull request, you agree that your work is released under the MIT licence, like the rest of Sumi, and that you have the right to share it. Don’t paste code from other projects unless their licence allows it.
New to pull requests? First Contributions walks you through your first one.