Task 21: avatar widget and image cache (#21) #45

Manually merged
charles merged 0 commits from task/21-ui-avatar-image-cache into foundation 2026-11-11 18:28:18 +00:00
Owner

What this builds

  • fluxer-core::media_urls (pure): avatar_url(&Endpoints, &UserPartial, size) -> AvatarSource { Url(Url) | Default(u8) } and guild_icon_url(&Endpoints, &Guild, size) -> Option<Url>, ported from the fork's AvatarUtils.ts and MediaProxyUtils.ts: {media}/avatars/{id}/{hash}.webp?size={snapped} through a port of buildMediaProxyURL, the 33-step size ladder, snapIconImageSize (clamped to 128..1024), and getDefaultAvatarIndex (id % 6). An empty or unparseable media endpoint falls back to the default avatar / None instead of panicking.
  • fluxer-ui::images: the ImageLoader trait (fn load(&self, Url) -> BoxFuture<'static, Result<RgbaImage, ImageError>>) and Images, the per-URL state (request returns an iced::Task, update, get). Each URL is loaded once.
  • fluxer-ui::widgets::avatar: avatar::view(source, size, presence: Option<UserStatus>) with a circle clip (Image::border_radius), the six default avatars copied from the web app into assets/avatars/, and a presence dot placed with the web app's AvatarStatusGeometry table and coloured from the --status-* tokens. avatar::request / avatar::resolve connect a core AvatarSource to Images.
  • fluxer-platform::images::ImageCache: ImageCache::new(cache_dir, max_mem_bytes), async fn get(&self, &Url) -> Result<RgbaImage, ImageCacheError>: memory (LRU by decoded bytes, 64 MiB default), then cache_dir/images/<sha256 of URL>, then reqwest. Decodes PNG, JPEG, GIF, WebP with the image crate. Implements ImageLoader; load spawns onto the tokio runtime the cache was created on, because iced polls tasks on its own executor.
  • The I/O boundary is recorded in crates/fluxer-ui/README.md and CLAUDE.md; READMEs of the three crates are updated.

Stacked on: task/16-ui-theme-fonts-icons, task/8-core-store-session

How it was tested

  • crates/fluxer-core/tests/media_urls.rs (9 tests): avatar_url_matches_web_app_for_known_hash, default_avatar_index_matches, size snapping, animated hashes requested static, guild icons, buildMediaProxyURL parameter order, unusable media endpoints.
  • crates/fluxer-platform/tests/images.rs (10 tests, wiremock): image_cache_hits_disk_after_first_fetch (server expects exactly one request; the second read uses a fresh cache on the same directory), memory hit, LRU eviction, WebP decode, non-image body, HTTP 404, corrupt disk entry refetched, non-HTTP scheme, unwritable cache directory, ImageLoader::load polled from a thread with no tokio context.
  • Unit tests in fluxer-ui for Images (load once, failure remembered, forgotten URL ignored) and the avatar widget (default avatars decode, status geometry table and interpolation, token colours, view builds for odd sizes).
  • Tests were written first and failed to compile against the missing modules; cargo xtask ci is green locally on the merged base and on this branch (screenshot step skipped locally, as on the base).

Deviations from the plan

  • The expected URL in avatar_url_matches_web_app_for_known_hash was derived by tracing the TypeScript by hand (device pixel ratio 1), not by executing it: the function needs the web app's bundler aliases and runtime config to run. Worth a second pair of eyes against the real client.
  • ImageCache::new takes the cache directory (impl AsRef<Path>) rather than a paths value: fluxer-platform has no paths type yet (Task 12).
  • Errors are concrete types: fluxer_ui::images::ImageError (cloneable, for iced messages) and fluxer_platform::images::ImageCacheError.
  • Extra files outside the task's list: crates/fluxer-ui/src/images.rs (the loader trait and image state are not avatar-specific), crates/fluxer-ui/src/widgets/mod.rs, crates/fluxer-ui/assets/avatars/.
  • avatar::view's source is a UI-side avatar::Source { Image(Handle) | Default(u8) | Placeholder }, produced by avatar::resolve(&images, &AvatarSource). A remote avatar shows a plain disc until it is loaded.
  • The web app cuts the status dot's surround out of the avatar with an SVG mask; here it is a ring in the backdrop colour (view assumes --background-secondary, view_on takes the colour). Idle/DND are plain coloured dots, not the web app's moon and bar shapes.
  • New dependencies: image 0.25 (no default features; png, jpeg, gif, webp) and sha2 0.11 in the workspace, and iced's image-without-codecs feature. fluxer-platform now depends on fluxer-ui (as the plan's interface requires), which pulls iced into it.
  • Images keeps every loaded handle for its lifetime (no eviction in the UI tier); fine for avatars and icons, to revisit when attachments arrive.
  • No side-by-side screenshots: nothing on this branch renders the widget in a window yet (shell is Task 17, harness Task 24).

Closes #21

🤖 Generated with Claude Code

## What this builds - **`fluxer-core::media_urls`** (pure): `avatar_url(&Endpoints, &UserPartial, size) -> AvatarSource { Url(Url) | Default(u8) }` and `guild_icon_url(&Endpoints, &Guild, size) -> Option<Url>`, ported from the fork's `AvatarUtils.ts` and `MediaProxyUtils.ts`: `{media}/avatars/{id}/{hash}.webp?size={snapped}` through a port of `buildMediaProxyURL`, the 33-step size ladder, `snapIconImageSize` (clamped to 128..1024), and `getDefaultAvatarIndex` (`id % 6`). An empty or unparseable media endpoint falls back to the default avatar / `None` instead of panicking. - **`fluxer-ui::images`**: the `ImageLoader` trait (`fn load(&self, Url) -> BoxFuture<'static, Result<RgbaImage, ImageError>>`) and `Images`, the per-URL state (`request` returns an `iced::Task`, `update`, `get`). Each URL is loaded once. - **`fluxer-ui::widgets::avatar`**: `avatar::view(source, size, presence: Option<UserStatus>)` with a circle clip (`Image::border_radius`), the six default avatars copied from the web app into `assets/avatars/`, and a presence dot placed with the web app's `AvatarStatusGeometry` table and coloured from the `--status-*` tokens. `avatar::request` / `avatar::resolve` connect a core `AvatarSource` to `Images`. - **`fluxer-platform::images::ImageCache`**: `ImageCache::new(cache_dir, max_mem_bytes)`, `async fn get(&self, &Url) -> Result<RgbaImage, ImageCacheError>`: memory (LRU by decoded bytes, 64 MiB default), then `cache_dir/images/<sha256 of URL>`, then reqwest. Decodes PNG, JPEG, GIF, WebP with the `image` crate. Implements `ImageLoader`; `load` spawns onto the tokio runtime the cache was created on, because iced polls tasks on its own executor. - The I/O boundary is recorded in `crates/fluxer-ui/README.md` and `CLAUDE.md`; READMEs of the three crates are updated. Stacked on: task/16-ui-theme-fonts-icons, task/8-core-store-session ## How it was tested - `crates/fluxer-core/tests/media_urls.rs` (9 tests): `avatar_url_matches_web_app_for_known_hash`, `default_avatar_index_matches`, size snapping, animated hashes requested static, guild icons, `buildMediaProxyURL` parameter order, unusable media endpoints. - `crates/fluxer-platform/tests/images.rs` (10 tests, wiremock): `image_cache_hits_disk_after_first_fetch` (server expects exactly one request; the second read uses a fresh cache on the same directory), memory hit, LRU eviction, WebP decode, non-image body, HTTP 404, corrupt disk entry refetched, non-HTTP scheme, unwritable cache directory, `ImageLoader::load` polled from a thread with no tokio context. - Unit tests in `fluxer-ui` for `Images` (load once, failure remembered, forgotten URL ignored) and the avatar widget (default avatars decode, status geometry table and interpolation, token colours, view builds for odd sizes). - Tests were written first and failed to compile against the missing modules; `cargo xtask ci` is green locally on the merged base and on this branch (screenshot step skipped locally, as on the base). ## Deviations from the plan - The expected URL in `avatar_url_matches_web_app_for_known_hash` was derived by tracing the TypeScript by hand (device pixel ratio 1), not by executing it: the function needs the web app's bundler aliases and runtime config to run. Worth a second pair of eyes against the real client. - `ImageCache::new` takes the cache directory (`impl AsRef<Path>`) rather than a `paths` value: `fluxer-platform` has no paths type yet (Task 12). - Errors are concrete types: `fluxer_ui::images::ImageError` (cloneable, for iced messages) and `fluxer_platform::images::ImageCacheError`. - Extra files outside the task's list: `crates/fluxer-ui/src/images.rs` (the loader trait and image state are not avatar-specific), `crates/fluxer-ui/src/widgets/mod.rs`, `crates/fluxer-ui/assets/avatars/`. - `avatar::view`'s `source` is a UI-side `avatar::Source { Image(Handle) | Default(u8) | Placeholder }`, produced by `avatar::resolve(&images, &AvatarSource)`. A remote avatar shows a plain disc until it is loaded. - The web app cuts the status dot's surround out of the avatar with an SVG mask; here it is a ring in the backdrop colour (`view` assumes `--background-secondary`, `view_on` takes the colour). Idle/DND are plain coloured dots, not the web app's moon and bar shapes. - New dependencies: `image` 0.25 (no default features; png, jpeg, gif, webp) and `sha2` 0.11 in the workspace, and iced's `image-without-codecs` feature. `fluxer-platform` now depends on `fluxer-ui` (as the plan's interface requires), which pulls iced into it. - `Images` keeps every loaded handle for its lifetime (no eviction in the UI tier); fine for avatars and icons, to revisit when attachments arrive. - No side-by-side screenshots: nothing on this branch renders the widget in a window yet (shell is Task 17, harness Task 24). Closes #21 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(ui): generated theme tokens, fonts and icons
All checks were successful
ci / Windows (x64) (push) Successful in 22s
ci / Windows (x64) (pull_request) Successful in 15s
ci / Linux (x86_64) (push) Successful in 1m22s
ci / Linux (x86_64) (pull_request) Successful in 1m23s
64430a109d
- xtask gen-theme --fork <path>: parses the Electron app's colour system,
  globals and message-layout CSS into crates/fluxer-ui/src/theme/tokens.rs
  (hsl/hsla/rgb/hex, saturation-factor calc, var() fallbacks, color-mix in
  srgb and oklab; rem to px).
- fluxer-ui::theme: tokens (DARK), palette::Theme with iced's Base and
  widget catalogs, fonts (Fluxer Sans/Mono as TTF) and icons (Phosphor SVGs).
- Adds iced 0.14 to the workspace; deny.toml allows BSL-1.0 and CC0-1.0 and
  ignores three unmaintained-crate advisories that iced pulls in.

Refs #16

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge origin/foundation into task/16-ui-theme-fonts-icons
All checks were successful
ci / Windows (x64) (push) Successful in 1m32s
ci / Windows (x64) (pull_request) Successful in 38s
ci / Linux (x86_64) (push) Successful in 1m28s
ci / Linux (x86_64) (pull_request) Successful in 1m34s
897ebaae93
Conflicts in xtask (both sides implemented dispatch stubs: gen-theme here,
vendor-spec/spec-check on foundation) and Cargo.lock resolved as the union.

Refs #16

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge origin/foundation into task/16-ui-theme-fonts-icons
All checks were successful
ci / Windows (x64) (push) Successful in 44s
ci / Linux (x86_64) (push) Successful in 1m41s
ci / Windows (x64) (pull_request) Successful in 52s
ci / Linux (x86_64) (pull_request) Successful in 1m31s
301b889ef7
Mechanical conflicts: both sides added workspace dependencies (iced, futures-util)
and Cargo.lock entries.

Refs #16

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #8

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): store skeleton and session reducer
All checks were successful
ci / Windows (x64) (push) Successful in 42s
ci / Linux (x86_64) (push) Successful in 1m0s
ci / Windows (x64) (pull_request) Successful in 41s
ci / Linux (x86_64) (pull_request) Successful in 1m5s
cacedcbbf7
Refs #8

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(ui): avatars with cached image loading
Some checks failed
ci / Windows (x64) (pull_request) Successful in 1m11s
ci / Windows (x64) (push) Successful in 55s
ci / Linux (x86_64) (pull_request) Failing after 1m32s
ci / Linux (x86_64) (push) Has been cancelled
5c961c3ca6
fluxer-core: media_urls ports the web app's AvatarUtils/MediaProxyUtils
(avatar_url, guild_icon_url, default avatar index, size snapping,
buildMediaProxyURL).
fluxer-ui: images::ImageLoader (the crate's single I/O boundary) with the
per-URL Images state, and widgets::avatar (round clip, bundled default
avatars, presence dot from the theme tokens).
fluxer-platform: images::ImageCache (reqwest, PNG/JPEG/GIF/WebP decode,
disk cache under cache_dir/images/<sha256>, in-memory LRU) implementing
ImageLoader.

Refs #21

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 21 (avatar widget and image cache), commit 5c961c3

Scope: git diff 00f9dee..origin/task/21-ui-avatar-image-cache.

Checks

  1. Tests named by the plan: all three exist and assert what the plan says. avatar_url_matches_web_app_for_known_hash expects https://fluxer.forked.io/media/avatars/1533494601170563073/a1b2c3d4e5f60718.webp?size=128; default_avatar_index_matches covers id % 6; image_cache_hits_disk_after_first_fetch uses a wiremock expect(1) with a second, fresh ImageCache, so the second read can only come from disk.
  2. Interfaces: avatar_url(&Endpoints, &UserPartial, u16) -> AvatarSource { Url(Url) | Default(u8) }, guild_icon_url, ImageCache::new, ImageCache::get, ImageLoader::load(&self, Url) -> BoxFuture<'static, Result<RgbaImage, _>> are present. Deviations are listed below; no other task's Interfaces block in the plan names these symbols.
  3. Invariants: fluxer-core gains no banned dependency (the xtask core-isolation step passes); fluxer-ui does no I/O beyond ImageLoader via Task::perform, recorded in CLAUDE.md and the crate README; body size, decoded size and allocation are capped and nothing in the server-data paths panics; no tokens in code or fixtures, and the image client sends no auth header.
  4. Review Focus: none of the five items belongs to this task.
  5. cargo xtask ci in the review worktree: green (fmt, clippy, deny, core isolation, tests; the screenshot step is skipped because FLUXER_SCREENSHOT_TESTS is not 1).

I compared the port line by line with the fork: AvatarUtils.ts (getUserAvatarURL, getGuildIconURL, getDefaultAvatarIndex, snapImageSizeWithinServerRange, icon range 128..1024), MediaProxyUtils.ts (snapMediaProxyImageSize, appendMediaProxyParams parameter order, animated removal, svg/data/blob bypass), the 33-rung size ladder, and the AvatarStatusGeometry.ts desktop table. All match. The six default avatar PNGs are byte-identical to the fork's.

Findings

  • minor: crates/fluxer-core/tests/media_urls.rs: the expected URL was hand-traced, not produced by running the TS function as Step 1 asks. My own trace of getUserAvatarURL → getMediaURL → setPathQueryParams → buildMediaProxyURL at DPR 1 gives the same string, so the value is right; the plan step is just not followed literally.
  • minor: crates/fluxer-platform/src/images.rs: ImageCache::new(cache_dir: impl AsRef<Path>, max_mem_bytes) instead of the plan's new(paths, ...), and get returns Result<RgbaImage, ImageCacheError>. Reasonable while there is no paths type (Task 12); Task 14 must pass the cache dir itself.
  • minor: crates/fluxer-ui/src/widgets/avatar.rs: avatar::view takes the UI-side avatar::Source (via avatar::resolve(&images, &AvatarSource)), not the core AvatarSource. Tasks 18 and 20 need the request / resolve / view trio; it is documented in the README.
  • minor: crates/fluxer-platform/Cargo.toml: fluxer-platform now depends on fluxer-ui, so every consumer of the platform crate (Task 12 store, Task 23 notifications) compiles iced. It follows from the plan's "trait in ui, impl in platform", but a small trait-only crate or a feature gate would avoid it. Worth a follow-up issue.
  • minor: crates/fluxer-platform/src/images.rs: ImageLoader::load needs the tokio Handle captured in ImageCache::new; a cache built outside a runtime fails every load with "no tokio runtime" (an error, not a panic). Task 14 must construct it inside the runtime. Also, two concurrent gets for the same URL both hit the network (the UI's Images dedups per URL, so this only matters for direct callers), and a memory hit clones the full pixel buffer.
  • minor: crates/fluxer-ui/src/images.rs: Images never evicts handles and a failed load stays failed until forget, so a transient network error leaves a placeholder for the session. No follow-up issue was opened; one should be before attachments or emoji use this path.
  • minor: crates/fluxer-ui/src/widgets/avatar.rs: the presence dot is a backdrop-coloured ring plus a plain dot rather than the web app's mask cutout, with no idle/dnd glyphs, and guild_icon_url takes a size where the web app always asks for 160. No side-by-side screenshots are attached (nothing renders the widget yet); they are owed with Tasks 17/24.

Verdict: APPROVE (0 blocking, 7 minor; local cargo xtask ci green).

## Independent review: Task 21 (avatar widget and image cache), commit 5c961c3 Scope: `git diff 00f9dee..origin/task/21-ui-avatar-image-cache`. **Checks** 1. Tests named by the plan: all three exist and assert what the plan says. `avatar_url_matches_web_app_for_known_hash` expects `https://fluxer.forked.io/media/avatars/1533494601170563073/a1b2c3d4e5f60718.webp?size=128`; `default_avatar_index_matches` covers `id % 6`; `image_cache_hits_disk_after_first_fetch` uses a wiremock `expect(1)` with a second, fresh `ImageCache`, so the second read can only come from disk. 2. Interfaces: `avatar_url(&Endpoints, &UserPartial, u16) -> AvatarSource { Url(Url) | Default(u8) }`, `guild_icon_url`, `ImageCache::new`, `ImageCache::get`, `ImageLoader::load(&self, Url) -> BoxFuture<'static, Result<RgbaImage, _>>` are present. Deviations are listed below; no other task's Interfaces block in the plan names these symbols. 3. Invariants: `fluxer-core` gains no banned dependency (the xtask core-isolation step passes); `fluxer-ui` does no I/O beyond `ImageLoader` via `Task::perform`, recorded in `CLAUDE.md` and the crate README; body size, decoded size and allocation are capped and nothing in the server-data paths panics; no tokens in code or fixtures, and the image client sends no auth header. 4. Review Focus: none of the five items belongs to this task. 5. `cargo xtask ci` in the review worktree: **green** (fmt, clippy, deny, core isolation, tests; the screenshot step is skipped because `FLUXER_SCREENSHOT_TESTS` is not 1). I compared the port line by line with the fork: `AvatarUtils.ts` (`getUserAvatarURL`, `getGuildIconURL`, `getDefaultAvatarIndex`, `snapImageSizeWithinServerRange`, icon range 128..1024), `MediaProxyUtils.ts` (`snapMediaProxyImageSize`, `appendMediaProxyParams` parameter order, `animated` removal, svg/data/blob bypass), the 33-rung size ladder, and the `AvatarStatusGeometry.ts` desktop table. All match. The six default avatar PNGs are byte-identical to the fork's. **Findings** - **minor**: `crates/fluxer-core/tests/media_urls.rs`: the expected URL was hand-traced, not produced by running the TS function as Step 1 asks. My own trace of `getUserAvatarURL` → `getMediaURL` → `setPathQueryParams` → `buildMediaProxyURL` at DPR 1 gives the same string, so the value is right; the plan step is just not followed literally. - **minor**: `crates/fluxer-platform/src/images.rs`: `ImageCache::new(cache_dir: impl AsRef<Path>, max_mem_bytes)` instead of the plan's `new(paths, ...)`, and `get` returns `Result<RgbaImage, ImageCacheError>`. Reasonable while there is no paths type (Task 12); Task 14 must pass the cache dir itself. - **minor**: `crates/fluxer-ui/src/widgets/avatar.rs`: `avatar::view` takes the UI-side `avatar::Source` (via `avatar::resolve(&images, &AvatarSource)`), not the core `AvatarSource`. Tasks 18 and 20 need the `request` / `resolve` / `view` trio; it is documented in the README. - **minor**: `crates/fluxer-platform/Cargo.toml`: `fluxer-platform` now depends on `fluxer-ui`, so every consumer of the platform crate (Task 12 store, Task 23 notifications) compiles iced. It follows from the plan's "trait in ui, impl in platform", but a small trait-only crate or a feature gate would avoid it. Worth a follow-up issue. - **minor**: `crates/fluxer-platform/src/images.rs`: `ImageLoader::load` needs the tokio `Handle` captured in `ImageCache::new`; a cache built outside a runtime fails every load with "no tokio runtime" (an error, not a panic). Task 14 must construct it inside the runtime. Also, two concurrent `get`s for the same URL both hit the network (the UI's `Images` dedups per URL, so this only matters for direct callers), and a memory hit clones the full pixel buffer. - **minor**: `crates/fluxer-ui/src/images.rs`: `Images` never evicts handles and a failed load stays failed until `forget`, so a transient network error leaves a placeholder for the session. No follow-up issue was opened; one should be before attachments or emoji use this path. - **minor**: `crates/fluxer-ui/src/widgets/avatar.rs`: the presence dot is a backdrop-coloured ring plus a plain dot rather than the web app's mask cutout, with no idle/dnd glyphs, and `guild_icon_url` takes a size where the web app always asks for 160. No side-by-side screenshots are attached (nothing renders the widget yet); they are owed with Tasks 17/24. **Verdict: APPROVE** (0 blocking, 7 minor; local `cargo xtask ci` green).
docs(ui): mark illustrative snippets as text, not ignored doctests
All checks were successful
ci / Windows (x64) (push) Successful in 57s
ci / Windows (x64) (pull_request) Successful in 54s
ci / Linux (x86_64) (push) Successful in 1m35s
ci / Linux (x86_64) (pull_request) Successful in 1m43s
2d16dfbfec
The Linux CI screenshot step runs 'cargo test --workspace -- --ignored',
which compiles 'ignore' doctests; the images.rs fragment is not a
compilable item and failed there.

Refs #21

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
charles manually merged commit 24e7c9d137 into foundation 2026-11-11 18:28:18 +00:00
Sign in to join this conversation.
No description provided.