Skip to content

New README backed by a head-to-head benchmark; blur behind the launcher (152/152 parity) - #233

Merged
hanthor merged 7 commits into
mainfrom
claude/modest-bell-xqa0vv
Sep 25, 2026
Merged

New README backed by a head-to-head benchmark; blur behind the launcher (152/152 parity)#233
hanthor merged 7 commits into
mainfrom
claude/modest-bell-xqa0vv

Conversation

@hanthor

@hanthor hanthor commented Sep 25, 2026

Copy link
Copy Markdown
Member

README and benchmarks

  • README rewrite. The README now covers what Compass is (with screenshots), why to choose it over Vicinae, how to install it from the TunaOS Flatpak remote (and other routes), a link to https://tunaos.org/compass, and credit to Vicinae.

  • Head-to-head benchmark. Every performance claim comes from a head-to-head run: Compass against the pinned, unmodified Vicinae 0.29.0 AppImage (SHA-256 checked), on the same machine, headless Sway with software rendering, median of 5 alternating runs:

    Compass Vicinae 0.29.0
    Engine ready to answer 96 ms 1,746 ms
    Launcher populated 0.9 s 2.3 s
    Keystroke to updated results 56 ms 153 ms
    Idle memory (PSS) 218 MiB 263 MiB
    Shared libraries loaded 46 136
    Program files 72 MB 310 MB

  • Losses are reported too. Per core, Compass's fuzzy scorer is 2–3× slower than Vicinae's; across 4 cores the two are about even. Compass also runs more threads. The README and docs/rust-engine/BENCHMARKS.md both say so.

  • Where the method lives. docs/rust-engine/BENCHMARKS.md has the method, versions, raw report and a "still to measure" list. scripts/bench/compare.sh reproduces the run, also as just bench-compare. It uses a private Sway, a D-Bus bus with no activatable services, a throwaway HOME and unshare --net. The per-core fuzzy comparison uses scripts/bench/fuzzy/cpp_rank.cpp and a fuzzy-throughput bin in compass-testkit.

  • Other docs. CONTRIBUTING, CUTOVER and HEAD-TO-HEAD are brought in line with the README.

Blur behind the card (ADR-0019)

  • New crate. crates/compass-wayland-foreign is a narrow unsafe bridge from the toolkit's raw window handles to a wayland-client proxy. It holds two unsafe calls in one allowed function; every invariant is documented, and the refusals are tested: not Wayland, not a wl_surface, an untracked proxy, and a missing libwayland.
  • The seam. Blur goes through a new compass_platform::WindowMaterial trait, implemented in vicinae. compass-ui never depends on the bridge, and the seam test says so.
  • Behaviour.
    • While the card is translucent, compass-ui asks for ext-background-effect blur behind the rounded card region.
    • Turning the tint off removes the blur.
    • A region is sent only when it changes.
    • A destroyed surface is never sent anything; that would be a protocol error on winit's shared display.
  • Tests. Headless Sway tests bridge a real toolkit surface. A blurring in-process compositor checks the region protocol.
  • Parity goes from 151/152 to 152/152 (scripts/ci/parity-score.py).
  • Not covered yet.
    • The layer-shell presentation: iced_layershell hands out no raw handles. The safe route is noted in PARITY.md.
    • A real blur on KWin or niri: that is VM-tier work.

Local gates: fmt, workspace clippy -D warnings, rustdoc -D warnings, and the tests of compass-ui, compass-platform, compass-wayland, compass-wayland-foreign and vicinae (including on headless Sway); the bench script tests and shellcheck also pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn

Generated by Claude Code

@claude
compass-ui: ViciScrollBar's thin rounded scrollbar for every scrollable
8e58053 
iced's default scrollbar is a 10px square rail and scroller. Every
scrollable now goes through crate::scroll::scrollable, which draws the
C++ ViciScrollBar: 6px wide, radius 3, no rail, the text colour faint at
rest and stronger under the pointer or while dragging.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn
@claude
Markdown views: draw in the launcher's font, not iced's generic sans
9226136 
Every Markdown view (an extension's Detail, the store detail page, the
store intros, the created-extension page) built its settings with
`markdown::Settings::with_text_size(14, &theme)`, whose `style.font` is
`Font::default()` -- the generic sans-serif -- while every other text
widget uses `LauncherApp::font()`. cosmic-text maps generic sans-serif
to a hard-coded "Open Sans"; where that family is missing (a stock
GNOME install) each span goes through its fallback list instead, and
bold spans of a variable default family land on whichever family has a
static 700 face (DejaVu Sans Bold, Cantarell Bold...), so the page's
text was in a different, mixed face from the rest of the launcher.

`LauncherApp::markdown_settings` now sets `style.font` to the launcher
font (code keeps iced's monospace) and all four views use it; the
store viewer's image placeholder uses the same font.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn
@claude
Publish the Flatpak to the TunaOS remote, with store screenshots
b0b51ad 
publish-flatpak.yaml takes the bundle a green Flatpak run on main
already built and smoke-tested, exports it as an OCI image to
ghcr.io/tuna-os/compass and records it in the remote's index through the
org's shared publish-flatpak-index step. It refuses to publish an image
without AppStream labels.

The metainfo gains a developer, screenshots, branding colours and a
first release. The screenshots are rendered through the paint tier by an
ignored test, regenerated with `just screenshots`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn
@claude
Merge the pre-squash history of this branch (#231 is already on main)
cfeafb5
@claude
Window material: an unsafe bridge to the launcher's surface, and blur…
dfb512a 
… behind the card

Closes the last amber parity cell, src/services/window-material Rust ✓
(152 of 152). The maintainer approved an unsafe exception (ADR-0019):

- compass-wayland-foreign: a Linux-only crate that does not inherit the
  workspace's forbid(unsafe_code); it denies unsafe, restates the other
  lints, and allows it in one function (adopt) with two blocks,
  Backend::from_foreign_display and ObjectId::from_ptr. Its safe API,
  bridge(&window), takes both raw-window-handle handles from one window,
  accepts only Wayland ones, checks the pointer is a wl_surface, refuses a
  surface that is not a wayland-rs proxy, names the client_system backend
  so the wrong one does not compile, and keeps one Connection per display
  for the process's life.
- compass_platform::WindowMaterial (the seam), implemented by
  vicinae::window_material over the bridge and
  compass_wayland::material::BackgroundEffects, handed to
  compass_ui::run_resident by the binary.
- compass-ui measures the card with a sensor keyed on tint and corner
  radius and asks through iced::window::run for the card's rounded
  rectangle while the card is translucent, none when it is not.
- BackgroundEffects drops effects of destroyed surfaces before sending,
  since set_blur_region on one is a protocol error on winit's display.

Under the xdg_toplevel presentation only: iced_layershell drops
window::run, a declared difference. Tested on headless Sway (the bridge)
and an in-process compositor that blurs (the region traffic); real blur
on KWin is VM tier.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn
@claude
README: why Compass over Vicinae, backed by a head-to-head benchmark
c4a50bc 
The README now leads with what Compass is and a measured comparison against
the pinned, unmodified Vicinae v0.29.0 AppImage: cold start (96 ms vs 1,746 ms
to IPC ready; 0.9 s vs 2.3 s to a populated launcher), keystroke to frame
(56 vs 153 ms), idle PSS (218 vs 263 MiB), 46 vs 136 shared objects and
72 MB vs 310 MB of program files. It also says where Compass loses: its fuzzy
scorer is 2-3x slower per core, and it runs more threads.

- scripts/bench/compare.sh and compare.py (just bench-compare): headless Sway,
  a private D-Bus bus with no activation, throwaway HOME/XDG, both engines
  under unshare --net, alternating runs, process trees found by an
  environment tag.
- scripts/bench/fuzzy/cpp_rank.cpp and compass-testkit's fuzzy-throughput
  bin: the two scorers over the same 10k haystack and queries.
- docs/rust-engine/BENCHMARKS.md: method, machine, raw per-run numbers,
  the SLA benches, and a still-to-measure list. The raw report is archived
  under benchmarks/2026-09-25-compare.
- Install: the TunaOS Flatpak remote (com.vicinae.Vicinae), CI bundle,
  flatpak-builder, the other packages and cargo. Stale migration-status
  prose and Vicinae-only instructions are gone; credit to Vicinae is kept.
- CONTRIBUTING.md points at Compass's tracker, not Vicinae's; CUTOVER.md
  no longer quotes 70/158.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UtGVEzDmYTdpsuEQErmmLn
@claude
Merge the pre-squash history of this branch (#232 is already on main)
409cb3a
@hanthor
hanthor merged commit c34b688 into main Sep 25, 2026
31 checks passed
hanthor pushed a commit that referenced this pull request Sep 25, 2026
@claude
Merge the pre-squash history of this branch (#233 is already on main)
360c642
@hanthor-hive-agent hanthor-hive-agent Bot mentioned this pull request Oct 1, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@hanthor @claude