feat(avatars): distinguish agents with svg squircles

[tellaho]

Category: improvement
User Impact: Agent avatars use a consistent squircle shape in conversations and identity surfaces, while identities without agent hints remain circular.

Problem: Mixed human/agent conversations are harder to scan when avatar shapes do not reliably distinguish them across surfaces and sizes.

Solution: Use one scalable SVG mask across the existing avatar primitives, keeping keyboard focus outside the clipped artwork. Shape comes from exact-key display hints—not names or imagery—and updates as available profile/library evidence changes.

Behavior and boundaries

• Message authors use a squircle for an original kind-40002 agent envelope, including after edits, or when their exact key has a profile/library hint.
• Thread participant stacks, membership activity, mention choices, and profiles use explicit is_agent/isAgent profile metadata or exact keys in the already-loaded session library. My Agents cards are agent-specific.
• These are self-declared display hints, not proof of ownership, membership, running state, or authority. A human declaring an agent hint can receive the agent treatment; no heuristic attempts to establish real-world identity type.
• Avatars do not trigger library reads or telemetry scans. Library hints remain lazy, and marker-only profile additions/removals refresh subscribers.
• Keep existing host/design-system ownership. Mask artwork only; profile buttons retain visible keyboard focus. No new execution, authorization, or persistence model.

File changes

docs/profiles.md
Explain shape rules, lazy display hints, and focus boundaries concisely; keep coverage separate from behavior.

src/bundled/agents/AgentsPage.tsx
Give actual agent-library cards the squircle variant.

src/bundled/mentions/MentionCompletion.tsx
Classify exact identities and refresh an open completion when library hints change.

src/bundled/mentions/MentionPicker.tsx
Keep human choices circular while marking known agent choices.

src/bundled/profiles/ProfilePanel.tsx
Apply exact-key agent hints while retaining main’s full-size portrait layout and original-resolution profile media.

src/features/agents/known.test.ts
Cover the combined profile/library identity projection.

src/features/agents/known.ts
Combine self-declared profile hints and already-loaded library keys; never infer from names.

src/features/agents/use-known.ts
Subscribe to existing display evidence without initiating library reads.

src/features/messages/ChannelTimeline.test.tsx
Keep timeline geometry fixtures compatible with the subscribed library projection.

src/features/messages/ChannelTimeline.tsx
Pass one subscribed identity projection to timeline consumers.

src/features/messages/MembershipRow.tsx
Shape each exact member identity and independently clip inset pictures/initials inside the overlap border; keep overflow counters circular and existing sizes unchanged.

src/features/messages/MessageRow.test.tsx
Cover human/agent shapes and the original agent-envelope hint without profile/library evidence.

src/features/messages/MessageRow.tsx
Separate clipped artwork from the interactive focus ring, clip inset reply-participant artwork, and use original agent-envelope evidence for message authors.

src/features/messages/Messages.module.css
Preserve an unmasked keyboard focus ring and load the shared artwork mask through CSS, keeping stylesheet imports out of the type-only author declarations.

src/features/messages/ThreadPanel.test.tsx
Supply the real library query contract in thread fixtures.

src/features/messages/ThreadPanel.tsx
Apply the identity projection to thread roots, replies, and participant stacks.

src/features/messages/membership-rows.test.tsx
Verify small media requests and decorative circle/squircle artwork coexist.

src/features/relay/contracts.ts
Represent profile and original-envelope hints as display-only data, not authority.

src/features/relay/fold.test.ts
Cover original event kinds through edits, including malformed and envelope-looking bodies.

src/features/relay/fold.ts
Preserve original kind-40002 evidence through existing message folding and edits.

src/features/relay/profile-details.test.ts
Cover marker-only additions/removals and reference-stable unchanged profile values.

src/features/relay/profile-directory.ts
Notify subscribers when agent metadata is the only profile change.

src/features/relay/profiles.ts
Retain explicit boolean is_agent/isAgent profile metadata.

src/shared/Avatar.tsx
Expose circle/squircle shapes through the existing legacy avatar primitive.

src/shared/design-system/styles/avatar-shape.css
Scale one shared SVG mask across sizes; keep circle defaults and interactive wrappers unmasked.

src/shared/design-system/styles/avatar-squircle.svg
Bundle the normalized squircle curve with a descriptive title.

src/shared/design-system/ui/Avatar.tsx
Add the shape variant without replacing Base UI behavior.

src/shared/design-system/ui/registry.ts
Document the proposed squircle variant and its display-only meaning alongside main’s fill size.

tests/browser/agents.spec.mjs
Assert squircle treatment for My Agents cards.

tests/browser/avatar-shapes.spec.mjs
Add painted-pixel, size (including fill), theme, viewport, pointer, and keyboard-focus assertions. Sample fractional bounds correctly and test the artwork inside overlap borders, not just their shape attributes. Use the existing mainline isolated-cache fixture helper, including cleanup if listening fails.

tests/browser/fixture.mjs
Provide explicit human/agent membership identities.

tests/browser/membership.spec.mjs
Assert per-identity shapes rather than relying on DOM order.

tests/browser/messages.spec.mjs
Cover human and agent authors in the shared timeline/thread UI.

tests/browser/profiles.spec.mjs
Check exact profile targets and human/agent shapes with the separated artwork wrapper.

tests/browser/typeahead.spec.mjs
Cover namesake human/agent choices and library-only updates without another keystroke or eager read.

tests/fixtures/avatar-shapes.html
Provide the isolated avatar regression fixture entry point.

tests/fixtures/avatar-shapes.tsx
Exercise real avatar consumers with local test data; this is not product screenshot evidence.

tests/fixtures/design-system/ui/componentSpecimens.tsx
Show squircle artwork and fallback variants in the design-system viewer.

tests/fixtures/mentions.tsx
Expose lazy library updates for completion regressions.

tests/fixtures/messages.tsx
Exercise agent-envelope rendering without a profile agent marker.

tests/fixtures/profiles.tsx
Supply an agent portrait with explicit profile metadata to cover squircle shape and fill size together.

Reproduction steps

1. Open a populated channel with a person and an agent. Confirm the person remains circular and the agent artwork paints as a full-sized squircle, not a tiny clipped patch.
2. Open a thread. Check authors and participant stacks; original agent-envelope authors should remain squircles even without profile/library hints and after a message edit.
3. Open mention autocomplete and the member picker. Namesake human/agent identities must remain distinct by exact key. Change loaded library hints while completion stays open: artwork should update without another keystroke.
4. Open human and agent profiles, inspect membership activity, and open My Agents. Check image and fallback shapes at small and large sizes.
5. Tab to a message avatar and activate it with Enter. Confirm the focus ring remains visible outside the artwork; pointer clicks should not add the keyboard-only ring.
6. Repeat visual checks in light/dark and narrow/intermediate/wide layouts.

Validation

Current head: d41c87c5bb383be92e0037da4b322a0c5bfed032; pushed to block/buzz-app:tho/svg-agent-squircles with an explicit lease and verified against the remote. The worktree is clean. Existing ready-for-review state was preserved; this is not a claim of full validation or merge readiness.

Rebased with merge history preserved onto main f0c6ac892fa3b5296e983ec7b02999dada9c9b6f. Resolutions retain shared design tokens, the contenteditable composer, full-size profile portraits, small avatar media requests, and link/typing behavior alongside display-only agent shapes. The inset fix is a5578c1; the post-rebase pixel-sampler/fixture corrections are d41c87c. No mainline assertion was removed or relaxed to bless integration.

Local results

Checked on macOS using repository-pinned tools. The final remaining-gate runner checked HEAD and clean status before each stage and recorded the unchanged head afterward.

• At d41c87c: whole-tree Biome, application/design TypeScript, design guards, frontend build, design build, 39 design unit tests, 20 Chromium/WebKit design-viewer tests, Rust formatting, and workspace/all-target Clippy passed.
• At d41c87c: complete Chromium/WebKit browser suite, including local-only measurement cases, finished 407 passed / 1 failed in 17.9 minutes. All avatar, membership, profile, completion, message/thread and agent cases passed. This is local execution time, not a CI benchmark or a performance-improvement claim.
• The sole browser failure is tests/browser/emoji.spec.mjs:298: WebKit reports the final custom emoji bottom at 1154.796875 versus the composer bottom at 1154.5625. A separate clean worktree at untouched main f0c6ac8 reproduces the identical assertion and coordinates; the complete emoji file passes in Chromium and fails in WebKit there too. Command: bin/pnpm test:browser tests/browser/emoji.spec.mjs --project chromium --project webkit --no-deps --workers=2 (1 passed / 1 failed, 8.2 seconds test execution). No tolerance, retry, skipped engine, or production workaround was added.
• At d41c87c: Tauri tests finished 11 passed / 1 failed. terminal::tests::real_spawn_fences_secrets_and_preserves_login_context remains blocked by the machine-managed ClickFix acknowledgement prompt in its temporary-HOME login shell. The security gate was not acknowledged or bypassed by the agent. Native terminal code is unchanged from main.
• The initial post-rebase scan at a5578c1 passed 1,565 Vitest tests / 148 files, 38 Node integration tests, and 16 plugin-manager Rust tests before the browser stage was interrupted for pixel-test debugging. Those production/unit/integration/Rust inputs are unchanged at d41c87c; only the avatar browser sampler, its fixture and one contenteditable browser assertion changed afterward. This interrupted scan is not counted as a full pass.
• The pinned repository pre-push gate was explicitly run at d41c87c alongside the preserved managed hooks: TypeScript and 776 related unit tests / 59 files passed. All PR commits were audited for DCO; all signatures verified. Hosted DCO Check passed at d41c87c.

Regression coverage and limits

The PR adds three browser test definitions (six engine cases), with no existing cases removed: actual avatar-mask paint/focus, exact-key namesake completion/picker wiring, and lazy library refresh through the open completion UI. Existing journeys gained representative shape assertions. The inset fix extends the existing paint case rather than adding another app-startup matrix. Low-level profile marker replacement and original-envelope preservation remain in Vitest.

The paint case covers light/dark and 390/900/1280px widths, all shared avatar sizes including fill, human circles, inset pictures/initials, unchanged 24px/20px reply and 28px/24px membership dimensions, and unmasked pointer/keyboard controls. A temporary removal of the inset mask failed the clipping assertion in both Chromium and WebKit; restoration passed both. The mutation was not committed. Pixel sampling respects fractional element coordinates and uses the actual panel surface as backdrop.

Hosted status and remaining acceptance

At the post-push snapshot, GitHub reports MERGEABLE, REVIEW_REQUIRED, and DCO Check successful. CI run 35015539132 is in progress/queued at d41c87c; CI green is not claimed, and no wait/poll loop was used. Repository rules require CI required, DCO, and reviewer/code-owner approval. No approval or merge is implied.

The complete local gate is not green because of the reproduced mainline WebKit emoji failure and managed-shell PTY blocker. Signed packaging, native-window/cross-platform acceptance, and fresh post-rebase live panel acceptance remain open. The reported Rizz reply-entry/member-added clipping was verified in the live app before rebase; classification was already squircle, and inset artwork clipping—not identity detection—was the correction. Historical screenshots below retain their original attribution and do not prove the final head.

Screenshots / visual acceptance

Captured from the actual populated worktree product at 76ef90439f0e7dea8b489072d4fcc82a5f48dea9, in Chrome against the desktop target's Vite frontend—not a fixture or component showcase. With the operator's approval, the target was restarted with a gitignored public BUZZ_DEV_VIEWER pin; the broker verified the selected identity and served live mode. No private key was extracted or committed.

Dark mode was selected through Settings. This build exposes no accent selector in Appearance; its existing blue-toned product styling is unchanged. Captures are cropped to the relevant identity surfaces to exclude unrelated channel lists and message content.

Channel member picker: human circle and agent squircle

Agent profile

My Agents card

Read-only DOM inspection confirmed Carl's message/profile artwork and participant-stack avatars use the SVG mask while tho remains circular. In this live channel, the legacy messages initially lacked a loaded agent hint; opening My Agents loaded the exact-key library evidence and ordinary navigation then showed Carl as a squircle. These captures therefore demonstrate library-backed display hints, not independent validation of the original kind-40002 path.

At that earlier capture, native-window capture was blocked by macOS permissions and thread-button activation did not open a thread. No messages or profile edits were submitted through the screenshot browser. Current automated coverage and remaining live/native gaps are reported above; these historical captures do not establish updated-main acceptance.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Review clear

No actionable code, product, or security blockers found at ef172998e70aac7d48fd533997000f10b4598a04, reviewed against base 3f824df94e8f4571b678fefd35de794c75c926b1. This is a source/metadata review, not approval or native/live acceptance.

• Identity and lifecycle: original kind-40002 evidence survives edits; explicit boolean profile markers invalidate selected-profile snapshots on addition/removal. Loaded-library keys remain exact-key, display-only evidence, with passive subscriptions and the existing clear/dispose fences. Mention membership and publication authority remain separate. Anchors: fold.ts:144–169, profile-directory.ts:41–68, use-known.ts.
• Integrated surfaces: traced timeline/thread authors, participant stacks, membership activity, both mention choosers, profiles, and My Agents through the shared mask. The outer message control stays unmasked; circle defaults, small media requests, and full-size profile sizing remain explicit. The external Composer Lab passes neither profiles nor agent-key projection, so its Message surface gets envelope-only classification; this is not automatic profile/library classification for every external caller. Anchors: MessageRow.tsx:106–133, avatar-shape.css, ProfilePanel.tsx:85–110.
• Evidence and limits: CI run 34887880374 is completed/success and bound to this exact head; every listed hosted check, including CI required and DCO, reports success. Inspected the new signed-fold, marker-update, lazy-completion, and painted-pixel/focus test sources. Independent consumer and primitive lanes are integrated. The focus wrapper’s --radius-sm comes from the pinned Tailwind 4.3.3 theme; the repository’s color reset does not remove it. Review used pinned Git objects on the authorized laptop, BLKLCJVVT954L.local, without changing the unrelated clean checkout at 06737cc1af201950d916992e04ab2bd28756498f. I did not check out, execute, build, or test PR code. The author-disclosed live profile/thread panel symptom and native/packaging acceptance remain unverified; historical screenshots are not evidence for this head. No PR-introduced cause for that live symptom was established.