Shell 20: platform-tray-trait-icons (#812) #884

Closed
charles wants to merge 0 commits from shell-20-platform-tray-trait-icons into shell
Owner

Stacked on: shell-8-core-tray-model-and

What was built

fluxer-platform::tray (spec §5.2, §6):

  • Tray trait (set(&TrayModel) -> Result<(), TrayError>, remove()), TrayEvent::{Activate { token }, ShowRequested, Item(TrayAction), Availability(TrayAvailability)}, TraySink = Arc<dyn Fn(TrayEvent) + Send + Sync>, TrayError::{Unsupported, Failed}.
  • system_tray(sink) -> Box<dyn Tray>: an UnsupportedTray on every OS until Tasks 21 / 22; it reports Availability(NoHost) once when made (so the window rules treat the window as trayless: close quits, a hidden window is shown) and refuses models with Unsupported.
  • FakeTray: records models and removals, shown(), set_failing, emit(event); clones share state.
  • flatten(&[TrayItem]) -> FlatMenu with FlatItem { id, parent, kind }, depth first; action_id / action_for_id: an action's id is its index in TrayAction::ALL + 1 (root 0); separators, submenus and a duplicated or unlisted action get ids from 1000 up. FlatMenu::action(id) maps a click back, children(parent).
  • icon::render(Appearance::{Colored, White, Black}, indicator, size) -> RgbaImage (straight RGBA) as D/TrayIconImage.ts:14-123: luminance cut-out (median body luminance, 10 %..50 % ramp, min contrast 32), glyph #ffffff / #1c1c1c, the dot #dd0000, radius 0.22, gap 0.0625, 4x4 subsamples, worked premultiplied as Electron does. Appearance::resolve(TrayAppearance, light_system_theme) = resolveTrayIconAppearance. icon::SIZES = 16, 22, 24, 32, 48, 64.
  • Dependency: resvg = { version = "0.45", default-features = false } (workspace + fluxer-platform): the SVG renderer iced's svg feature already brings, same version; Cargo.lock gains only the edge. cargo deny green.

Tests

crates/fluxer-platform/tests/tray_icon.rs: mono_is_single_colour_with_alpha, dot_is_top_right_red_with_gap, no_dot_without_indicator, sizes_render (plus 0, 1, 2, 7, 256 px), fake_records_and_emits (also: the token is not in Debug), menu_flattening_keeps_order_and_ids, and extra colored_keeps_the_logo_colours, appearance_follows_the_model_and_the_theme, a_system_without_a_back_end_says_so; unit tests in tray/{mod,icon}.rs. Seen failing (no module) before the implementation, then passing. Icons also checked by eye (dumped PNGs; a disc with the roll cut out, the dot with its ring). FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally. No real-desktop test exists for this task (none run). No Windows-only code in this PR.

Deviations / notes for the reviewer

  • Logo: flaxative-small.svg below 32 px and flaxative.svg from 32 px (the packaged icons' split, packaging/logo/README.md); the spec names only the small one.
  • The original's Linux monochrome crop + 22/16 margin (:125-190) is not in render (the logo already fills its square); left to the Linux back end if wanted.
  • Additions beyond the Interfaces block: Appearance::resolve, UnsupportedTray, FlatMenu/FlatItem/FlatKind, ROOT_ID, icon::DOT_RGB.
  • Stacking merge of shell-8 into current shell: conflicts in fluxer-core README, app.rs, shell/mod.rs, tests/shell_ports.rs resolved keeping both sides; tests/shell_window.rs::hidden_without_any_tray_is_shown_at_once relaxed from "no effects" to "no window command, no timer" (Task 8 now sends the tray model with that event). Bug #883 opened: Task 8's window_visible and Task 9's window.visible disagree after WindowRequest::Hidden.

Strings copied: none (no labels in this task).

Closes #812

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

Stacked on: shell-8-core-tray-model-and ## What was built `fluxer-platform::tray` (spec §5.2, §6): - `Tray` trait (`set(&TrayModel) -> Result<(), TrayError>`, `remove()`), `TrayEvent::{Activate { token }, ShowRequested, Item(TrayAction), Availability(TrayAvailability)}`, `TraySink = Arc<dyn Fn(TrayEvent) + Send + Sync>`, `TrayError::{Unsupported, Failed}`. - `system_tray(sink) -> Box<dyn Tray>`: an `UnsupportedTray` on every OS until Tasks 21 / 22; it reports `Availability(NoHost)` once when made (so the window rules treat the window as trayless: close quits, a hidden window is shown) and refuses models with `Unsupported`. - `FakeTray`: records models and removals, `shown()`, `set_failing`, `emit(event)`; clones share state. - `flatten(&[TrayItem]) -> FlatMenu` with `FlatItem { id, parent, kind }`, depth first; `action_id` / `action_for_id`: an action's id is its index in `TrayAction::ALL` + 1 (root 0); separators, submenus and a duplicated or unlisted action get ids from 1000 up. `FlatMenu::action(id)` maps a click back, `children(parent)`. - `icon::render(Appearance::{Colored, White, Black}, indicator, size) -> RgbaImage` (straight RGBA) as `D/TrayIconImage.ts:14-123`: luminance cut-out (median body luminance, 10 %..50 % ramp, min contrast 32), glyph `#ffffff` / `#1c1c1c`, the dot `#dd0000`, radius 0.22, gap 0.0625, 4x4 subsamples, worked premultiplied as Electron does. `Appearance::resolve(TrayAppearance, light_system_theme)` = `resolveTrayIconAppearance`. `icon::SIZES` = 16, 22, 24, 32, 48, 64. - Dependency: `resvg = { version = "0.45", default-features = false }` (workspace + fluxer-platform): the SVG renderer iced's `svg` feature already brings, same version; Cargo.lock gains only the edge. `cargo deny` green. ## Tests `crates/fluxer-platform/tests/tray_icon.rs`: `mono_is_single_colour_with_alpha`, `dot_is_top_right_red_with_gap`, `no_dot_without_indicator`, `sizes_render` (plus 0, 1, 2, 7, 256 px), `fake_records_and_emits` (also: the token is not in `Debug`), `menu_flattening_keeps_order_and_ids`, and extra `colored_keeps_the_logo_colours`, `appearance_follows_the_model_and_the_theme`, `a_system_without_a_back_end_says_so`; unit tests in `tray/{mod,icon}.rs`. Seen failing (no module) before the implementation, then passing. Icons also checked by eye (dumped PNGs; a disc with the roll cut out, the dot with its ring). `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. No real-desktop test exists for this task (none run). No Windows-only code in this PR. ## Deviations / notes for the reviewer - Logo: `flaxative-small.svg` below 32 px and `flaxative.svg` from 32 px (the packaged icons' split, `packaging/logo/README.md`); the spec names only the small one. - The original's Linux monochrome crop + 22/16 margin (`:125-190`) is not in `render` (the logo already fills its square); left to the Linux back end if wanted. - Additions beyond the Interfaces block: `Appearance::resolve`, `UnsupportedTray`, `FlatMenu`/`FlatItem`/`FlatKind`, `ROOT_ID`, `icon::DOT_RGB`. - Stacking merge of shell-8 into current shell: conflicts in fluxer-core README, `app.rs`, `shell/mod.rs`, `tests/shell_ports.rs` resolved keeping both sides; `tests/shell_window.rs::hidden_without_any_tray_is_shown_at_once` relaxed from "no effects" to "no window command, no timer" (Task 8 now sends the tray model with that event). Bug #883 opened: Task 8's `window_visible` and Task 9's `window.visible` disagree after `WindowRequest::Hidden`. Strings copied: none (no labels in this task). Closes #812 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
shell::tray: tray_model (tooltip, unread dot, appearance, the menu in the
original's order and strings, D/DesktopTray.ts:312-315,407-532 and
D/MainI18n.ts:57-117), each TrayAction reduced to the existing actions
or a window / shell command, the model sent only when it changed, and a
hidden window shown again when the tray goes away
(D/DesktopTray.ts:594-600).

Refs #800

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Keeps both sides in fluxer-core's README, app.rs, shell/mod.rs and shell_ports.rs; the
Task 9 window test no longer forbids the tray model Task 8 sends with the first event.

Refs #812

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The Tray trait, TrayEvent and TraySink, system_tray (UnsupportedTray, which reports
NoHost, until Tasks 21 and 22), FakeTray, the menu flattening with the stable
id <-> TrayAction table, and tray::icon::render as D/TrayIconImage.ts (fork
fluxer_desktop/src/main/TrayIconImage.ts:14-123): the packaged logo rasterised with
resvg 0.45 (already in the tree through iced), the monochrome cut-out and the dot.

Refs #812

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Author
Owner

Review: Shell 20 (tray trait, icons, fake), independent reviewer

Reviewed git diff 0f916b1b..7156aec4 (this task's own commit) plus the stacking merge's relaxed shell_window.rs test, as the implementer asked.

Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on 7156aec4, run locally: all steps passed (tray_icon.rs: 9/9).

Checks

  1. Plan tests: mono_is_single_colour_with_alpha, dot_is_top_right_red_with_gap, no_dot_without_indicator, sizes_render, fake_records_and_emits and menu_flattening_keeps_order_and_ids all exist and check the spec's values: radius 0.22 × size, gap 0.0625 × size, #dd0000, glyph #ffffff / #1c1c1c, sizes 16/22/24/32/48/64. They also check the action-id ↔ TrayAction::ALL table in both directions, that ids are unique and stable, and that the token's Debug prints ….
  2. Interfaces: Tray { set(&TrayModel) -> Result<(), TrayError>, remove() }, TrayEvent::{Activate { token }, ShowRequested, Item(TrayAction), Availability(TrayAvailability)}, TraySink = Arc<dyn Fn(TrayEvent) + Send + Sync>, system_tray(sink) -> Box<dyn Tray>, FakeTray and icon::render(Appearance::{Colored, White, Black}, indicator, size) -> RgbaImage all exist as the plan writes them. The id table is in tray/mod.rs, so Task 22's menu_ids_stable can be tested on every OS.
  3. Invariants: no change to fluxer-core or fluxer-ui. resvg 0.45 has no default features and only adds an edge to Cargo.lock, not a new crate. No I/O beyond include_bytes! of the packaged SVGs. No secrets or paths. render(…, 0) returns an empty image and never panics.
  4. Parity, checked against fluxer_desktop/src/main/TrayIconImage.ts:
    • The constants match :14-28, including BGR→RGB for DOT_BGR and GLYPH_BGR.
    • luminance keeps the original's coefficients (0.0722·B + 0.7152·G + 0.2126·R) on RGBA.
    • bodyLuminance, paintMonochromeGlyph and paintTrayIndicatorDot follow :41-123 line for line: the 4×4 subsamples, the centre at (w − r, r), and the clipped minX/maxY loop.
    • Appearance::resolve matches resolveTrayIconAppearance :30-39 (no macOS).
    • The original paints the dot before it adds the Linux margin (:228-240), so leaving the margin to Task 21 keeps the same order.
  5. Review Focus: no item belongs to Task 20 directly. For item 6 (honest capability reporting), UnsupportedTray reports NoHost once and refuses set with a typed TrayError::Unsupported instead of doing nothing silently.

Stacking merge, shell_window.rs: the relaxed hidden_without_any_tray_is_shown_at_once still asserts no window command, no timer and that the window is not visible. The only effect it now allows is Task 8's tray model, so the test still checks what Task 9 meant. Acceptable.

Findings

  • minor: the spec (§6) says flaxative-small.svg, "rasterised once". render uses the small logo below 32 px and flaxative.svg from 32 px, following packaging/logo/README.md, and it parses and rasterises the SVG again on every call. Neither is wrong, but Tasks 21 and 22 should cache the pictures per (appearance, indicator, size) rather than call render on every model change. The logo choice is a spec deviation and should be recorded in the PR body for Charles.
  • minor: after a monochrome pass the port keeps unrounded float channels until the dot is painted, where the original rounds them to bytes. The difference is at most 1 per channel and cannot be seen. Note only.
  • minor: structural ids (from 1000) depend on how many structural rows come before them. Adding the voice block, for example, renumbers the separators and submenus after it, while action ids stay stable. dbusmenu's layout revision handles this. Task 21's update_changes_only_what_changed should compare rows by action or label, not by structural id.
  • minor: UnsupportedTray::new calls the sink synchronously on the caller's thread, unlike a real back end's thread. The doc says so. The runtime (Task 33) must not hold a lock the sink needs while it calls system_tray.

Verdict: approved. No blocking findings and the local gate is green.

## Review: Shell 20 (tray trait, icons, fake), independent reviewer Reviewed `git diff 0f916b1b..7156aec4` (this task's own commit) plus the stacking merge's relaxed `shell_window.rs` test, as the implementer asked. **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on 7156aec4, run locally: **all steps passed** (tray_icon.rs: 9/9). ### Checks 1. **Plan tests:** `mono_is_single_colour_with_alpha`, `dot_is_top_right_red_with_gap`, `no_dot_without_indicator`, `sizes_render`, `fake_records_and_emits` and `menu_flattening_keeps_order_and_ids` all exist and check the spec's values: radius 0.22 × size, gap 0.0625 × size, `#dd0000`, glyph `#ffffff` / `#1c1c1c`, sizes 16/22/24/32/48/64. They also check the action-id ↔ `TrayAction::ALL` table in both directions, that ids are unique and stable, and that the token's `Debug` prints `…`. 2. **Interfaces:** `Tray { set(&TrayModel) -> Result<(), TrayError>, remove() }`, `TrayEvent::{Activate { token }, ShowRequested, Item(TrayAction), Availability(TrayAvailability)}`, `TraySink = Arc<dyn Fn(TrayEvent) + Send + Sync>`, `system_tray(sink) -> Box<dyn Tray>`, `FakeTray` and `icon::render(Appearance::{Colored, White, Black}, indicator, size) -> RgbaImage` all exist as the plan writes them. The id table is in `tray/mod.rs`, so Task 22's `menu_ids_stable` can be tested on every OS. 3. **Invariants:** no change to fluxer-core or fluxer-ui. `resvg` 0.45 has no default features and only adds an edge to Cargo.lock, not a new crate. No I/O beyond `include_bytes!` of the packaged SVGs. No secrets or paths. `render(…, 0)` returns an empty image and never panics. 4. **Parity, checked against `fluxer_desktop/src/main/TrayIconImage.ts`:** - The constants match `:14-28`, including BGR→RGB for `DOT_BGR` and `GLYPH_BGR`. - `luminance` keeps the original's coefficients (0.0722·B + 0.7152·G + 0.2126·R) on RGBA. - `bodyLuminance`, `paintMonochromeGlyph` and `paintTrayIndicatorDot` follow `:41-123` line for line: the 4×4 subsamples, the centre at (w − r, r), and the clipped minX/maxY loop. - `Appearance::resolve` matches `resolveTrayIconAppearance` `:30-39` (no macOS). - The original paints the dot before it adds the Linux margin (`:228-240`), so leaving the margin to Task 21 keeps the same order. 5. **Review Focus:** no item belongs to Task 20 directly. For item 6 (honest capability reporting), `UnsupportedTray` reports `NoHost` once and refuses `set` with a typed `TrayError::Unsupported` instead of doing nothing silently. **Stacking merge, `shell_window.rs`:** the relaxed `hidden_without_any_tray_is_shown_at_once` still asserts no window command, no timer and that the window is not visible. The only effect it now allows is Task 8's tray model, so the test still checks what Task 9 meant. Acceptable. ### Findings - **minor:** the spec (§6) says `flaxative-small.svg`, "rasterised once". `render` uses the small logo below 32 px and `flaxative.svg` from 32 px, following `packaging/logo/README.md`, and it parses and rasterises the SVG again on every call. Neither is wrong, but Tasks 21 and 22 should cache the pictures per (appearance, indicator, size) rather than call `render` on every model change. The logo choice is a spec deviation and should be recorded in the PR body for Charles. - **minor:** after a monochrome pass the port keeps unrounded float channels until the dot is painted, where the original rounds them to bytes. The difference is at most 1 per channel and cannot be seen. Note only. - **minor:** structural ids (from 1000) depend on how many structural rows come before them. Adding the voice block, for example, renumbers the separators and submenus after it, while action ids stay stable. dbusmenu's layout revision handles this. Task 21's `update_changes_only_what_changed` should compare rows by action or label, not by structural id. - **minor:** `UnsupportedTray::new` calls the sink synchronously on the caller's thread, unlike a real back end's thread. The doc says so. The runtime (Task 33) must not hold a lock the sink needs while it calls `system_tray`. **Verdict: approved.** No blocking findings and the local gate is green.
Author
Owner

Merged into shell by hand (the merge API returns 405); the commits are in the branch.

Merged into `shell` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-18 11:58:25 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.