Entity images: avatars, guild icons (animated), banners #214

Manually merged
charles merged 0 commits from feat-entity-images into main 2026-11-12 05:16:35 +00:00
Owner

Stacked on: #197 (which is stacked on #192 and #189). Merge those first; this branch starts from fix-member-list.

Why nothing showed

The client had URL builders for still avatars and guild icons (fluxer_core::media_urls) and an image cache (fluxer_platform::ImageCache), but nothing connected them: the shell never built an Images store, apps/fluxer passed no loader, and every view drew initials or a bundled default avatar. Nothing was ever requested, which is why the log had no image warnings. The URL shapes were right for a real instance ({media}/avatars/..., with endpoints.media = https://<host>/media in a real discovery document), but only the still variant existed. Most real avatars carry the a_ (animated) marker.

What this does

URLs (fluxer-core, media_urls, ported from fluxer_app/src/features/user/utils/AvatarUtils.ts), all below endpoints.media:

Image Path Animated variant
user avatar avatars/{user}/{hash}.webp?size=160 a_{hash}.webp?size=160&animated=true
member avatar guilds/{guild}/users/{user}/avatars/{hash}.webp?size=160, else the user's same rule
guild icon icons/{guild}/{hash}.webp?size=160 same rule
guild banner banners/{guild}/{hash}.webp?size=480 same rule
group DM icon icons/{channel}/{hash}.webp?size=160 never requested (the original does not animate it)

The still variant drops the a_ from the file name. The proxy's default for animated is "the hash has a_" (fluxer_media_proxy/src/server/params.rs:91-95), and it answers animated .webp requests with an animated WebP, or with a GIF for a GIF original (format_policy.rs:8-26). Sizes are the web app's values at device pixel ratio 1 (MediaProxyAssetSizes.ts), snapped to the proxy's ladder within its ranges. A hash that is not one plain path segment gives no URL.

Loading (fluxer-ui images, fluxer-platform ImageCache): ImageLoader::load now returns LoadedImage::{Still, Animated(frames)}.

  • The cache decodes animated WebP, GIF and APNG with the existing image crate, sniffing the bytes rather than trusting the extension.
  • Frame delays of 10 ms or less become 100 ms, as in Chromium.
  • An animation over 48 MiB decoded or 1000 frames falls back to its first frame.
  • The disk tier is now bounded at 256 MiB; least recently used files go first, and a read refreshes the file's time.
  • The UI's Images keeps GPU handles, one per frame, under a 96 MiB budget with LRU by last request.
  • Decoding runs on tokio's blocking pool; the UI thread only swaps handles.
  • libfluxwebp is not used: the repo does not depend on it.

Where they show (sizes and shapes from the original's CSS; citations in screens/main/media.rs and the views):

  • guild rail: 44 px, round, 30 % corners when selected or hovered; the acronym without an icon or while loading.
  • channel sidebar: the guild banner at the top, width / (16/9) high, cropped from the top centre, with the 40 px shade and the header over it (GuildHeader.module.css:48-82).
  • DM list: 32 px avatar with presence; for a group DM, its icon or the accent-colour disc.
  • user area: 32 px with presence, where only a status dot used to be.
  • member list: 32 px, per-guild avatar, offline at 0.3.
  • message authors: 40 px, per-guild avatar.
  • voice participants: 24 px; 28 px in collapsed stacks.
  • call tiles, compact call, DM call row, incoming call: 80 px for the incoming call.

Placeholders, as in the original (BaseAvatar.module.css:34-54): an avatar is a --background-secondary-alt disc while it loads and after a failure. The original keeps the skeleton and does not swap in the default avatar. Users without an avatar get the bundled default.

When animations play (the original's rule, useShouldAnimate.ts:45-49; avatars and icons have no setting):

  • guild icon: while its rail item is hovered.
  • message author: while the message row is hovered.
  • member list, DM list, user area: while the avatar itself is hovered.
  • voice and call avatars: while the person speaks.
  • guild banner: always while the synced "Automatically play GIFs" (gif_auto_play, default on) is on, otherwise on hover.

Hover is cleared when the window loses focus (useHover.ts). A hovered animation starts at its first frame. The shell subscribes to window::frames() only while a loaded animation is on screen.

Parity: added accessibility-gif-autoplay (Accessibility → Animation, planned, owner 7). The banner already honours the server's value; the toggle itself is sub-project 7's. UserSettings::gif_auto_play() was added in fluxer-proto, with the fixture field.

Devserver: GET /media/{path} serves the proxy's image paths with pictures drawn in code (crates/fluxer-devserver/src/images.rs): small, license-clean, nothing downloaded. An a_ hash asked for with animated=true gets a 4-frame animated WebP, written by hand because the image crate cannot encode one. The fixtures now give the signed-in user an animated avatar, ada a still one, the "Forked" guild an animated icon and a banner, and the second guild a still icon. All hashes are synthetic.

Dependencies

No new crates. Workspace crates gained edges:

  • fluxer-devserver → image (already a workspace dependency).
  • dev-dependencies: fluxer-platform → fluxer-devserver, and fluxer-ui → fluxer-devserver (the generator, for tests).

Goldens changed (reference renderer: lavapipe, Ubuntu 22.04)

All of these now show the generated pictures where they used to show initials or default avatars. The user area shows the 32 px avatar instead of a status dot. The selected guild shows its banner.

  • main-general.png: rail icons, banner, message, member list and user area avatars.
  • sidebar_voice.png, voice_panel_connected.png, voice_panel_failed.png: the same screen, plus voice participant avatars.
  • call_view_4.png, call_view_compact.png: tile and compact avatars, rail, banner, member list.
  • soundboard_popout.png, participant_menu.png: the call screen under the popout or menu.
  • incoming_call.png: the caller's avatar, over the main screen.

Unchanged: login.png, settings-appearance.png, settings_voice.png.

Tests

  • fluxer-core/tests/media_urls.rs: every builder against the fixture discovery document (shaped like a real instance's), still and animated variants, member-avatar fallback, banner and group DM sizes, hostile hashes.
  • fluxer-platform/tests/images.rs:
    • an animated WebP decodes to every frame with its delay;
    • a GIF under a .webp name decodes, with 0 ms delays raised to 100 ms;
    • one-frame and oversized animations become still images;
    • the disk tier stays within its budget.
  • fluxer-ui images unit tests: the byte budget evicts the least recently requested image; frame timing and looping; degenerate animations.
  • fluxer-ui/tests/media.rs:
    • what the screen wants: still images, plus the animated variant only of what is hovered;
    • the DM list avatar;
    • the placeholder before loading and after a failure (not the default avatar), the loaded image, and the animated frame advancing with the clock.
  • apps/fluxer/tests/images.rs (end to end): the runtime logs in to the devserver; the avatar and the animated guild icon are fetched by the real ImageCache from the devserver's /media/... paths and reach what the main screen draws, and the icon is a real animation.
  • cargo xtask ci is green. The screenshot tests pass on lavapipe in the Ubuntu 22.04 image.

Not verifiable without the real server

Look at these first on fluxer.forked.io:

  1. The proxy answers the animated URLs with an animated WebP (or a GIF), and the decoder plays them at the right speed.
  2. The members' per-guild avatars come from guilds/{g}/users/{u}/avatars/....
  3. The banner's crop and height look like the web app's at your sidebar width.

No real image was fetched while building this.

Follow-ups

#207 group DM avatar cluster · #208 banner collapse on scroll, 30 vh cap, detached mode · #209 retrying failed loads · #210 role icons · #211 typing bar, reply preview and autocomplete avatars · #212 user and member banners, guild splash (profile and invite screens) · #213 reduced motion, data saver, and HiDPI request sizes

🤖 Generated with Claude Code

Stacked on: #197 (which is stacked on #192 and #189). Merge those first; this branch starts from `fix-member-list`. ## Why nothing showed The client had URL builders for still avatars and guild icons (`fluxer_core::media_urls`) and an image cache (`fluxer_platform::ImageCache`), but nothing connected them: the shell never built an `Images` store, `apps/fluxer` passed no loader, and every view drew initials or a bundled default avatar. Nothing was ever requested, which is why the log had no image warnings. The URL shapes were right for a real instance (`{media}/avatars/...`, with `endpoints.media` = `https://<host>/media` in a real discovery document), but only the still variant existed. Most real avatars carry the `a_` (animated) marker. ## What this does **URLs** (`fluxer-core`, `media_urls`, ported from `fluxer_app/src/features/user/utils/AvatarUtils.ts`), all below `endpoints.media`: | Image | Path | Animated variant | | --- | --- | --- | | user avatar | `avatars/{user}/{hash}.webp?size=160` | `a_{hash}.webp?size=160&animated=true` | | member avatar | `guilds/{guild}/users/{user}/avatars/{hash}.webp?size=160`, else the user's | same rule | | guild icon | `icons/{guild}/{hash}.webp?size=160` | same rule | | guild banner | `banners/{guild}/{hash}.webp?size=480` | same rule | | group DM icon | `icons/{channel}/{hash}.webp?size=160` | never requested (the original does not animate it) | The still variant drops the `a_` from the file name. The proxy's default for `animated` is "the hash has `a_`" (`fluxer_media_proxy/src/server/params.rs:91-95`), and it answers animated `.webp` requests with an animated WebP, or with a GIF for a GIF original (`format_policy.rs:8-26`). Sizes are the web app's values at device pixel ratio 1 (`MediaProxyAssetSizes.ts`), snapped to the proxy's ladder within its ranges. A hash that is not one plain path segment gives no URL. **Loading** (`fluxer-ui` `images`, `fluxer-platform` `ImageCache`): `ImageLoader::load` now returns `LoadedImage::{Still, Animated(frames)}`. - The cache decodes animated WebP, GIF and APNG with the existing `image` crate, sniffing the bytes rather than trusting the extension. - Frame delays of 10 ms or less become 100 ms, as in Chromium. - An animation over 48 MiB decoded or 1000 frames falls back to its first frame. - The disk tier is now bounded at 256 MiB; least recently used files go first, and a read refreshes the file's time. - The UI's `Images` keeps GPU handles, one per frame, under a 96 MiB budget with LRU by last request. - Decoding runs on tokio's blocking pool; the UI thread only swaps handles. - `libfluxwebp` is not used: the repo does not depend on it. **Where they show** (sizes and shapes from the original's CSS; citations in `screens/main/media.rs` and the views): - guild rail: 44 px, round, 30 % corners when selected or hovered; the acronym without an icon or while loading. - channel sidebar: the guild banner at the top, `width / (16/9)` high, cropped from the top centre, with the 40 px shade and the header over it (`GuildHeader.module.css:48-82`). - DM list: 32 px avatar with presence; for a group DM, its icon or the accent-colour disc. - user area: 32 px with presence, where only a status dot used to be. - member list: 32 px, per-guild avatar, offline at 0.3. - message authors: 40 px, per-guild avatar. - voice participants: 24 px; 28 px in collapsed stacks. - call tiles, compact call, DM call row, incoming call: 80 px for the incoming call. **Placeholders, as in the original** (`BaseAvatar.module.css:34-54`): an avatar is a `--background-secondary-alt` disc while it loads and after a failure. The original keeps the skeleton and does not swap in the default avatar. Users without an avatar get the bundled default. **When animations play** (the original's rule, `useShouldAnimate.ts:45-49`; avatars and icons have no setting): - guild icon: while its rail item is hovered. - message author: while the message row is hovered. - member list, DM list, user area: while the avatar itself is hovered. - voice and call avatars: while the person speaks. - guild banner: always while the synced **"Automatically play GIFs"** (`gif_auto_play`, default on) is on, otherwise on hover. Hover is cleared when the window loses focus (`useHover.ts`). A hovered animation starts at its first frame. The shell subscribes to `window::frames()` only while a loaded animation is on screen. **Parity**: added `accessibility-gif-autoplay` (Accessibility → Animation, planned, owner 7). The banner already honours the server's value; the toggle itself is sub-project 7's. `UserSettings::gif_auto_play()` was added in `fluxer-proto`, with the fixture field. **Devserver**: `GET /media/{path}` serves the proxy's image paths with pictures drawn in code (`crates/fluxer-devserver/src/images.rs`): small, license-clean, nothing downloaded. An `a_` hash asked for with `animated=true` gets a 4-frame animated WebP, written by hand because the `image` crate cannot encode one. The fixtures now give the signed-in user an animated avatar, ada a still one, the "Forked" guild an animated icon and a banner, and the second guild a still icon. All hashes are synthetic. ## Dependencies No new crates. Workspace crates gained edges: - `fluxer-devserver` → `image` (already a workspace dependency). - dev-dependencies: `fluxer-platform` → `fluxer-devserver`, and `fluxer-ui` → `fluxer-devserver` (the generator, for tests). ## Goldens changed (reference renderer: lavapipe, Ubuntu 22.04) All of these now show the generated pictures where they used to show initials or default avatars. The user area shows the 32 px avatar instead of a status dot. The selected guild shows its banner. - `main-general.png`: rail icons, banner, message, member list and user area avatars. - `sidebar_voice.png`, `voice_panel_connected.png`, `voice_panel_failed.png`: the same screen, plus voice participant avatars. - `call_view_4.png`, `call_view_compact.png`: tile and compact avatars, rail, banner, member list. - `soundboard_popout.png`, `participant_menu.png`: the call screen under the popout or menu. - `incoming_call.png`: the caller's avatar, over the main screen. Unchanged: `login.png`, `settings-appearance.png`, `settings_voice.png`. ## Tests - `fluxer-core/tests/media_urls.rs`: every builder against the fixture discovery document (shaped like a real instance's), still and animated variants, member-avatar fallback, banner and group DM sizes, hostile hashes. - `fluxer-platform/tests/images.rs`: - an animated WebP decodes to every frame with its delay; - a GIF under a `.webp` name decodes, with 0 ms delays raised to 100 ms; - one-frame and oversized animations become still images; - the disk tier stays within its budget. - `fluxer-ui` `images` unit tests: the byte budget evicts the least recently requested image; frame timing and looping; degenerate animations. - `fluxer-ui/tests/media.rs`: - what the screen wants: still images, plus the animated variant only of what is hovered; - the DM list avatar; - the placeholder before loading and after a failure (not the default avatar), the loaded image, and the animated frame advancing with the clock. - `apps/fluxer/tests/images.rs` (end to end): the runtime logs in to the devserver; the avatar and the animated guild icon are fetched by the real `ImageCache` from the devserver's `/media/...` paths and reach what the main screen draws, and the icon is a real animation. - `cargo xtask ci` is green. The screenshot tests pass on lavapipe in the Ubuntu 22.04 image. ## Not verifiable without the real server Look at these first on fluxer.forked.io: 1. The proxy answers the animated URLs with an animated WebP (or a GIF), and the decoder plays them at the right speed. 2. The members' per-guild avatars come from `guilds/{g}/users/{u}/avatars/...`. 3. The banner's crop and height look like the web app's at your sidebar width. No real image was fetched while building this. ## Follow-ups #207 group DM avatar cluster · #208 banner collapse on scroll, 30 vh cap, detached mode · #209 retrying failed loads · #210 role icons · #211 typing bar, reply preview and autocomplete avatars · #212 user and member banners, guild splash (profile and invite screens) · #213 reduced motion, data saver, and HiDPI request sizes 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Solve the fork's ALTCHA captcha in fluxer-api
All checks were successful
ci / Linux (x86_64) (push) Successful in 16m3s
ci / Windows (x64) (push) Successful in 16m12s
d281e073da
A 400 CAPTCHA_REQUIRED / INVALID_CAPTCHA carrying an ALTCHA v2 challenge
is now solved by the client (PBKDF2-HMAC-SHA-256 over nonce || counter_be32,
counters from 0 until the key starts with keyPrefix) and the same request is
sent again with X-Captcha-Token, at most twice per request, as the web
app's CaptchaInterceptor does for every request. The search runs in
spawn_blocking on up to 8 threads, bounded by 60 s and the challenge's
expiry, and stops when the request is dropped. The token is byte for byte
the web client's encoding.

ApiError::CaptchaRequired is left for captchas the client cannot solve
(unknown provider, malformed challenge, timeout, both solutions refused);
INVALID_CAPTCHA maps to it instead of a plain 400 that the core read as
wrong credentials. The login screen's message says so.

Test vector fixtures/captcha/altcha_login.json was produced by the fork's
own AltchaProvider; the API tests run against a mock that verifies tokens
the way the fork does. Adds ring (already in the graph via rustls) as a
direct dependency of fluxer-api.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`threads` was logged before the cap of 8 (the web app's MAX_SOLVER_WORKERS)
that `solve` applies, so a 32-core machine logged threads=32 while 8 ran.
Clamp before logging; behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Read READY as a real Fluxer server sends it
All checks were successful
ci / Linux (x86_64) (push) Successful in 14m30s
ci / Windows (x64) (push) Successful in 15m57s
3bf4ee7931
The server deduplicates users in READY: guilds[].members[].user is
{"id"} only and the full users are in the top-level `users` list
(session_ready_collect.erl). fluxer-proto required a full user on every
member, so a real READY failed to parse as a whole and the client showed
no guilds, no DMs and "Unknown User".

- fluxer-proto: `UserRef` (full user or `{"id"}` reference) for
  GuildMember::user, Presence::user (the offline PRESENCE_UPDATE sent when
  a friend/group-DM subscription is dropped) and GUILD_MEMBER_REMOVE's
  user (always a reference). `ReadyPayload::resolve_users()` fills the
  references from `users` and `user`.
- Every list of ReadyPayload / GuildReadyData is read leniently: a
  malformed entry is dropped with a warning instead of losing the
  session; a malformed guild object leaves `properties: None`. Adds
  `tracing` to fluxer-proto for that warning.
- fluxer-core: members and presences that are references add nothing to
  the user cache; names come from READY.users, unknown users show as
  Unknown User.
- fixtures/gateway/ready.json now has the real structure (member user
  references, `users` with every member, relationships without `user`,
  empty guild presences, sessions/version/...), with the same fake
  identities. The devserver resolves it before indexing message authors.
- tests/replay.rs in fluxer-core: with FLUXER_REPLAY_DIR set, replays a
  --record recording through the parsers and the store and reports
  mismatches by key path and redacted error only; skipped otherwise.
- Regression tests: references resolved via `users`, an unknown member
  user id kept, malformed members/channels/users/guilds dropped without
  failing READY, references in GUILD_MEMBER_REMOVE and PRESENCE_UPDATE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Subscribe to guild member lists as the web app does
All checks were successful
ci / Linux (x86_64) (push) Successful in 37m5s
ci / Windows (x64) (push) Successful in 29m8s
0b6c986ffd
The real server sends only the user's own member in READY and no guild
presences; the other members arrive in GUILD_MEMBER_LIST_UPDATE after an
op 14 (LAZY_REQUEST) subscription, which the client never sent.

- fluxer-proto: LazyRequest/GuildSubscription/MemberListRange, the
  GUILD_MEMBER_LIST_UPDATE and GUILD_SYNC dispatches, with a fixture.
- fluxer-core: MemberLists sends {active, sync} on guild select and the
  shown channel's member list ranges, again after every reconnect; keeps
  the server list and feeds member_list, users and presences from it;
  falls back to READY's members when no answer comes. GUILD_CREATE and
  GUILD_SYNC add their partial members instead of replacing them.
- fluxer-ui: group headers show the server's count.
- fluxer-devserver: READY and GUILD_CREATE carry only the signed-in
  member; op 14 is answered with a server-shaped member list, and
  presence changes resend it. New end-to-end test.

Follow-ups: #195 (scroll ranges past 1,000 rows), #196 (PASSIVE_UPDATES).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Show avatars, guild icons (animated too) and banners
All checks were successful
ci / Linux (x86_64) (push) Successful in 15m22s
ci / Windows (x64) (push) Successful in 15m20s
9a7369e7ec
Nothing reached the screen before: the shell never built an image store and
the app passed no loader, so every view drew initials or a default avatar.

- fluxer-core: still and animated media URLs for user and member avatars,
  guild icons and banners, and group DM icons (AvatarUtils.ts), with
  hash checks.
- fluxer-proto: UserSettings::gif_auto_play.
- fluxer-platform: decode animated WebP, GIF and APNG frames and their
  delays; bound the disk tier.
- fluxer-ui: LoadedImage/Picture with a byte-bounded store; a media module
  for hover state, the animation clock and the wanted URLs. Images now show
  in the rail, the sidebar banner, the DM list, the user area, the member
  list, message authors, voice rows and the call surfaces, with the
  original's placeholders and animation rules.
- fluxer-devserver: serve generated pictures (a hand-built animated WebP)
  at the proxy's paths; fixtures get synthetic hashes.
- apps/fluxer: inject the ImageCache.
- Goldens redrawn on lavapipe; parity entry for "Automatically play GIFs".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
charles referenced this pull request from a commit 2026-11-12 05:16:22 +00:00
charles manually merged commit b493918451 into main 2026-11-12 05:16:35 +00:00
Sign in to join this conversation.
No description provided.