feat(mascot): floating desktop mascot via native NSPanel + WKWebView (macOS)

[senamakel]

Summary

• Adds a tray-toggleable floating mascot anchored to the bottom-right pixel corner of the primary screen on macOS.
• Hosts the existing <YellowMascot> Remotion player inside a native NSPanel + WKWebView instead of a Tauri webview, so the window is actually transparent.
• Click-through is always-on (ignoresMouseEvents=true); a 20Hz Foundation timer detects when the cursor enters the home rect and animates the panel one mascot-height up the screen, returning home as soon as the cursor leaves.

Problem

We wanted a "floating desktop character" that would live on top of any app, not block clicks, and politely move out of the way when the user reaches for something underneath it. Two things made this non-trivial:

1. The vendored tauri-cef runtime (drives every existing OpenHuman window) cannot render transparent windowed-mode browsers — CEF clamps BrowserSettings.background_color alpha to 0xFF for windowed browsers, and the runtime doesn't enable off-screen rendering. A transparent: true Tauri WebviewWindow ends up opaque on screen.
2. Tauri's runtime is one-per-process: you can't selectively use tauri-runtime-wry (WKWebView/WebView2/etc.) for a single window inside a CEF app. Every Tauri-managed window in this codebase has to go through CEF.

Solution

Bypass Tauri's runtime entirely for this one window on macOS:

• New app/src-tauri/src/mascot_native_window.rs (macOS-only) creates a borderless NonactivatingPanel + embedded WKWebView directly via objc2-app-kit / objc2-web-kit. The panel is non-opaque, status-bar-level, can-join-all-spaces+transient (so it floats above fullscreen apps), shadowless, and ignoresMouseEvents=true. The WKWebView uses the canonical setValue:NO forKey:@"drawsBackground" KVC trick so the page CSS shows through.
• The webview loads the same Vite dev URL as the main window, with ?window=mascot appended. app/src/main.tsx was updated to detect that URL param before touching any Tauri API (since this webview lives outside Tauri's runtime) and mount a tiny MascotWindowApp that renders just <YellowMascot face="idle" />.
• New Tauri commands mascot_window_show / mascot_window_hide delegate to the native module on macOS and return an error elsewhere. A "Toggle floating mascot" entry was added to the existing tray menu.
• Hover-to-flee is implemented entirely on the Rust side: a Foundation NSTimer (50ms tick) compares NSEvent.mouseLocation() against the panel's home rect; entering it kicks off setFrame:display:animate: to a HopUp slot one panel-height above home, leaving brings it back. No JS bridge needed.

Trade-offs

• macOS only. Linux/Windows would each need their own native webview path (webkit2gtk, WebView2). The Tauri commands return an error there for now.
• Dev-only. resolve_page_url reads app.config().build.dev_url; production bundle support needs either a tiny localhost HTTP server in the shell or file:// loading with ESM/CORS workarounds. Documented in the module-level doc comment.
• No IPC bridge yet. The mascot face is hard-coded to idle until we wire a WKScriptMessageHandler to push real agent state in. Also means there's no in-page close button — toggle from the tray.
• Click-through is always on, so the panel can't be dragged. Acceptable since it's anchored to a fixed corner.

Submission Checklist

• N/A: prototype-level macOS-native code with no testable surface — the Rust module is a thin wrapper around Cocoa/WebKit calls and the React entry is a 12-line component. Will add tests once the IPC bridge / production bundle path lands.
• N/A: changed lines are 100% native Cocoa/WebKit FFI and a passive React render — no testable logic for diff-cover to evaluate; coverage gate would not measure anything meaningful here.
• N/A: behaviour-only change; no feature added to the matrix yet (mascot panel is not a tracked product feature pending wiring to real state).
• N/A: no matrix feature IDs apply.
• No new external network dependencies introduced (mock backend used per docs/TESTING-STRATEGY.md)
• N/A: not a release-cut surface — opt-in tray entry, not on a default user path.
• N/A: no linked issue.

Impact

• Platform: macOS desktop only. Other desktops are unaffected (the tray entry still appears but mascot_window_show returns an error).
• Runtime: adds a 50ms repeating Foundation timer while the mascot is visible; trivial CPU cost. Adds two new macOS deps (objc2-web-kit, plus NSTimer + block2 features on objc2-foundation). No new network deps.
• Security: WKWebView loads the same dev URL the main window uses, scoped to dev mode. The KVC drawsBackground private API is the standard wry/Electron approach; no new attack surface.
• Migration: none. Off by default; appears only when the user toggles the tray entry.

Related

• Closes:
• Follow-up PR(s)/TODOs:
  • Production bundle URL path (localhost server or file:// + bundled HTML).
  • WKScriptMessageHandler bridge so the host can push real agent state (face changes, show/hide on context).
  • Linux + Windows native paths if we want the mascot cross-platform.
  • Lighter Vite entry (mascot.html) so first paint isn't gated on the full app bundle.

Summary by CodeRabbit

• New Features
  • Floating mascot window for macOS with tray-menu toggle to show/hide.
  • Mascot runs as a standalone transparent window and supports launching with ?window=mascot.
  • Interactive hover animations that animate the mascot along the right edge.
• Enhancements
  • Visual tuning options for mascot rendering (adjustable shadow opacity and compact arm shading).
• Chores
  • macOS dependency updated to explicitly enable NSTimer and block2 features.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c3b97078-dfe0-408e-b3e6-50267f0d5e5d

📥 Commits

Reviewing files that changed from the base of the PR and between b8dc370 and 3e3eb46.

📒 Files selected for processing (3)

• app/src-tauri/src/lib.rs
• app/src-tauri/src/mascot_native_window.rs
• app/src/main.tsx

✅ Files skipped from review due to trivial changes (2)

• app/src-tauri/src/lib.rs
• app/src-tauri/src/mascot_native_window.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• app/src/main.tsx

---

📝 Walkthrough

Walkthrough

Adds a macOS-only floating mascot window: enables macOS dependency features, implements an NSPanel+WKWebView mascot host with hover-driven animations and show/hide/is_open plumbing, wires Tauri commands and a tray toggle, and adds frontend routing plus a MascotWindowApp and mascot visual props/styles.

Changes

Floating Mascot Window

Layer / File(s)	Summary
Dependency Features app/src-tauri/Cargo.toml	objc2-foundation updated to { version = "0.3.2", features = ["NSTimer", "block2"] } for macOS builds.
Native macOS Implementation app/src-tauri/src/mascot_native_window.rs	New NSPanel + WKWebView mascot host: show(app) resolves dev or bundled page source (appends ?window=mascot), computes bottom-right square frame, builds transparent non-activating click-through NSPanel, installs WKWebView (disables background drawing), spawns repeating NSTimer to poll cursor and animate between Home and HopUp slots; hide() tears down panel/timer; is_open() reports thread-local state.
Tauri Wiring & Tray app/src-tauri/src/lib.rs	Adds macOS-gated mascot_native_window mod; new Tauri commands mascot_window_show / mascot_window_hide (and mascot_native_window_is_open), registers them in invoke_handler, and adds a tray menu item "Toggle floating mascot" with handler that toggles show/hide.
Frontend Window Routing app/src/main.tsx	Detects ?window=mascot early and treats it as a standalone window via isStandaloneWindow; prevents default hash routing and deep-link listener for standalone windows; renders MascotWindowApp for mascot window.
Mascot UI Component & Styling app/src/mascot/MascotWindowApp.tsx, app/src/index.css	Adds MascotWindowApp rendering a transparent full-screen wrapper mounting YellowMascot (default idle) and passing groundShadowOpacity/compactArmShading; CSS extends overlay selectors to html[data-window='mascot'] for transparent background/hidden overflow/unselectable text.
Mascot Visual Props & SVG app/src/features/human/Mascot/YellowMascot.tsx, app/src/features/human/Mascot/yellow/MascotCharacter.tsx	Adds optional props groundShadowOpacity?: number and compactArmShading?: boolean; threads them through useMemo and component selection; MascotCharacter uses groundShadowOpacity for radial gradient stops and switches arm-shadow color-matrix constants when compactArmShading is set.

Sequence Diagram

sequenceDiagram
    actor User
    participant Frontend as Frontend (React)
    participant Tauri as Tauri Backend
    participant Native as macOS Native (NSPanel)
    participant WK as WKWebView
    participant Timer as NSTimer

    User->>Frontend: Click tray "Toggle floating mascot" / request show
    Frontend->>Tauri: invoke mascot_window_show()
    Tauri->>Native: show(app)
    Native->>Native: Resolve page source (append window=mascot)
    Native->>Native: Compute frame & build NSPanel
    Native->>WK: Create WKWebView and load URL/file
    Native->>Timer: Spawn repeating hover NSTimer
    Timer->>Native: Poll cursor position
    Native->>Native: Animate panel between Home/HopUp
    User->>Frontend: Request hide
    Frontend->>Tauri: invoke mascot_window_hide()
    Tauri->>Native: hide()
    Native->>Timer: Invalidate timer
    Native->>Native: Order out panel & drop webview

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly Related PRs

• tinyhumansai/openhuman#1200: Touches YellowMascot/mascot UI sources used by this PR.
• tinyhumansai/openhuman#1147: Related mascot UI changes and defaults.
• tinyhumansai/openhuman#1193: Related mascot component additions and variants.

Suggested Reviewers

• M3gA-Mind

Poem

🐰 I hopped in on a cocoa breeze,
A panel drifts where pixels please,
Webview hums and timers keep,
Mascot peeks from corner deep,
I wave my paw — the desktop's pleased.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately describes the main change: adding a floating desktop mascot on macOS using native NSPanel and WKWebView, which is the primary objective of this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/src-tauri/src/lib.rs`:
- Around line 961-970: The tray "Toggle floating mascot" MenuItem is always
created with MenuItem::with_id as mascot_item but the handler
(mascot_window_show) will fail on Windows and on macOS release until the prod
URL exists; change the code so mascot_item is only constructed and added to the
menu on platforms/builds where mascot_window_show is supported: wrap the
MenuItem::with_id call and its inclusion in the Menu::with_items array in a
cfg/conditional (e.g., cfg!(not(windows)) and the macOS-release check that
verifies the production URL exists), and ensure any handler registration
referencing mascot_item/mascot_window_show is likewise gated so no broken menu
entry is shipped.

In `@app/src-tauri/src/mascot_native_window.rs`:
- Around line 154-165: Replace the focus-dependent NSScreen::mainScreen() call
in bottom_right_frame with the primary screen obtained from
NSScreen::screens(mtm).first(), and use that screen's frame instead of the
current map/unwrap_or_else that falls back to the hard-coded 1440x900; adjust
the same change for the other occurrence at the referenced block (lines
~230–244) so both use NSScreen::screens(mtm).first() to compute x/y with
PANEL_SIZE and PANEL_MARGIN and remove the hard-coded fallback to ensure the
panel anchors to the menu-bar host screen.

In `@app/src/main.tsx`:
- Around line 33-40: The code unconditionally calls getActiveUserIdFromCore()
even in mascot mode where isMascotWindow is true (and in native WKWebView paths
that will reject), causing bootRender() to be delayed; update the bootstrap to
skip calling getActiveUserIdFromCore() when isMascotWindow is true (or when
tauriRuntimeAvailable() is false/native WKWebView), ensuring bootRender() is
invoked immediately for mascot windows; adjust both places that perform the
active-user bootstrap (the initial call near isMascotWindow and the later block
around the other bootstrap) to short-circuit and proceed to bootRender() without
awaiting getActiveUserIdFromCore() when isMascotWindow is set.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 500ca663-3094-4e06-8682-65b0cf8fb88a

📥 Commits

Reviewing files that changed from the base of the PR and between 62516ba and 8224eb6.

⛔ Files ignored due to path filters (1)

• app/src-tauri/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (6)

• app/src-tauri/Cargo.toml
• app/src-tauri/src/lib.rs
• app/src-tauri/src/mascot_native_window.rs
• app/src/index.css
• app/src/main.tsx
• app/src/mascot/MascotWindowApp.tsx

[coderabbitai]

🧹 Nitpick comments (1)

app/src/features/human/Mascot/yellow/MascotCharacter.tsx (1)

601-653: 💤 Low value

Consider applying compactArmShading to filter f13 (steady right arm) for consistency.

The steady right arm filter (f13) still uses hardcoded color matrices while the waving right arm (f4) and left arm (f5) now use the computed armHighlightMatrix / rightArmShadowMatrix / leftArmShadowMatrix. When compactArmShading is enabled, this arm will retain the warm yellow tints while the others use darker neutrals, creating visual inconsistency at small render sizes.

♻️ Proposed fix to apply computed matrices to f13

             <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1" />
-            <feColorMatrix
-              type="matrix"
-              values="0 0 0 0 0.973501 0 0 0 0 0.909066 0 0 0 0 0.671677 0 0 0 1 0"
-            />
+            <feColorMatrix type="matrix" values={armHighlightMatrix} />
             <feBlend mode="normal" in2="shape" result="effect1_innerShadow" />
             ...
             <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1" />
-            <feColorMatrix
-              type="matrix"
-              values="0 0 0 0 0.796078 0 0 0 0 0.576471 0 0 0 0 0.0980392 0 0 0 0.8 0"
-            />
+            <feColorMatrix type="matrix" values={leftArmShadowMatrix} />

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/src/features/human/Mascot/yellow/MascotCharacter.tsx` around lines 601 -
653, The steady right arm filter id={p('f13')} still uses hardcoded
feColorMatrix values; update it to use the computed matrices when
compactArmShading is enabled so shading matches the other arms. Specifically, in
MascotCharacter (filter f13) replace the hardcoded highlight and shadow
feColorMatrix inputs with armHighlightMatrix and the appropriate
rightArmShadowMatrix/leftArmShadowMatrix logic (same approach used in filters f4
and f5), and ensure the conditional uses compactArmShading to select the
computed matrix values so small-render consistency is preserved.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@app/src/features/human/Mascot/yellow/MascotCharacter.tsx`:
- Around line 601-653: The steady right arm filter id={p('f13')} still uses
hardcoded feColorMatrix values; update it to use the computed matrices when
compactArmShading is enabled so shading matches the other arms. Specifically, in
MascotCharacter (filter f13) replace the hardcoded highlight and shadow
feColorMatrix inputs with armHighlightMatrix and the appropriate
rightArmShadowMatrix/leftArmShadowMatrix logic (same approach used in filters f4
and f5), and ensure the conditional uses compactArmShading to select the
computed matrix values so small-render consistency is preserved.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f415416d-70e9-4aa6-81af-f41ff8d888e0

📥 Commits

Reviewing files that changed from the base of the PR and between 8224eb6 and 5495d9a.

📒 Files selected for processing (4)

• app/src-tauri/src/mascot_native_window.rs
• app/src/features/human/Mascot/YellowMascot.tsx
• app/src/features/human/Mascot/yellow/MascotCharacter.tsx
• app/src/mascot/MascotWindowApp.tsx

✅ Files skipped from review due to trivial changes (1)

• app/src/mascot/MascotWindowApp.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• app/src-tauri/src/mascot_native_window.rs