fix(mascot): swap to yellow mascot via @remotion/player

[senamakel]

Summary

• Swap the dark Ghosty on the Human page for the yellow mascot, rendered via @remotion/player.
• Reuse the Remotion-authored mascot sources (Idle / Thinking / Talking) as the source of truth for the SVG + animation logic.
• Map the existing MascotFace lifecycle (thinking/speaking/listening/etc.) onto the right Remotion composition per state.
• Make the mascot loop seamlessly: snap every periodic oscillator (bob, head-dot drift, sway, lipsync, blink, wave) to a whole number of cycles within durationInFrames, and add an optional thinking out-ramp so frame 0 == frame N.

Problem

The previous Ghosty mascot is real-time-clock based and visually distinct from the yellow mascot maintained in remotion/. We want the yellow mascot in the desktop app, but porting the SVG + animation system into the app's real-time renderer would duplicate logic and drift over time. Additionally, the yellow mascot's sine-driven oscillators didn't divide the composition duration cleanly, so playing it on a loop produced visible pops at the wrap.

Solution

• Add @remotion/player (+ remotion, @remotion/zod-types, zod) to app/.
• Copy the Remotion mascot sources into app/src/features/human/Mascot/yellow/ and rewrite their relative imports.
• New YellowMascot.tsx wraps <Player>, picks a composition based on face, and explicitly calls playerRef.play() on mount / variant change since autoPlay is unreliable across browsers and strict-mode mounts.
• Make MascotCharacter loop-clean: helper functions snap each oscillator's frequency to the nearest value that fits an integer cycle count in durationInFrames. The thinking variant gets in/out ramps (thinkInStartSec/thinkInEndSec/thinkOutStartSec/thinkOutEndSec) so it returns to idle at the loop boundary.
• HumanPage.tsx now renders <YellowMascot face={face} /> instead of <Ghosty face viseme />. Visemes are intentionally dropped — the yellow mascot has its own talking lipsync.
• Ghosty and viseme exports are kept so existing tests still pass and the legacy renderer remains available.

Submission Checklist

• N/A: visual / integration change with no behavioral logic to assert in unit tests; the yellow mascot's animation timings are deterministic from useVideoConfig() and verified visually
• N/A: presentational swap with no computational paths added (no Vitest/cargo coverage targets to grow)
• N/A: behaviour-only change — no new feature rows for the coverage matrix
• N/A: no new feature IDs introduced
• N/A: @remotion/player runs entirely client-side, no backend or network dependency added
• N/A: does not touch release-cut surfaces in the manual smoke checklist
• N/A: no linked issue

Impact

• Desktop: Human page now renders the yellow mascot. Bundle grows by @remotion/player + remotion (~few hundred KB pre-gzip). Mascot updates in remotion/ propagate to the app via the copied files.
• No backend, mobile, or CLI impact.

Related

• Closes:
• Follow-up PR(s)/TODOs: consolidate the duplicated mascot sources between remotion/ and app/src/features/human/Mascot/yellow/ into a shared internal package.

Summary by CodeRabbit

• New Features

  • Replaced the previous mascot with an animated yellow mascot supporting idle, talking, and thinking poses, plus loop-aligned thinking timing.
  • Added animated loading spinner and pulsing recording face for richer visual feedback.
  • Mascot now plays as an embedded animated player with responsive sizing and automatic playback.

• Chores

  • Added Remotion runtime and Zod type/runtime packages to support new animations.

[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: 4df371a0-8b50-46a9-870a-c7c33936ddd2

📥 Commits

Reviewing files that changed from the base of the PR and between 957a771 and d19cf21.

📒 Files selected for processing (2)

• app/src/features/human/Mascot/YellowMascot.tsx
• app/src/features/human/Mascot/yellow/MascotThinking.tsx

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

• app/src/features/human/Mascot/yellow/MascotThinking.tsx
• app/src/features/human/Mascot/YellowMascot.tsx

---

📝 Walkthrough

Walkthrough

Adds a Remotion-based yellow mascot system: SVG mascot core with multiple variants (Idle, Talking, Thinking), Remotion Player wrapper, configurable thinking timing, new face overlays, package dependency additions, and HumanPage integration replacing Ghosty.

Changes

Yellow Mascot System

Layer / File(s)	Summary
Dependencies app/package.json	Added remotion, @remotion/player, @remotion/zod-types at 4.0.454, and pinned zod to 4.3.6.
Public Exports / Integration app/src/features/human/Mascot/index.ts, app/src/features/human/HumanPage.tsx	Exported YellowMascot/props from mascot barrel; swapped Ghosty → YellowMascot in HumanPage and removed viseme prop usage while keeping useHumanMascot call.
Player Wrapper & Variant Selection app/src/features/human/Mascot/YellowMascot.tsx	New YellowMascot component selecting between Idle/Talking/Thinking variants based on face/arm, constructs inputProps, renders a looping Remotion Player, and imperatively starts playback on variant change.
Core Animation Component & Schema app/src/features/human/Mascot/yellow/MascotCharacter.tsx	New mascotSchema (Zod) and MascotCharacter SVG component with frame-driven animations: bob, blink/sleep, lip-sync, arm/greeting, thinking pose, Zzz letters, idPrefix namespacing, and many loop-safe motion primitives.
Face Overlays app/src/features/human/Mascot/yellow/RecordingFace.tsx, .../LoadingFace.tsx	Added RecordingFace (pulsing dot halo) and LoadingFace (rotating arc) SVG components used as alternate faces.
Variant Wrappers app/src/features/human/Mascot/yellow/MascotIdle.tsx, .../MascotTalking.tsx, .../MascotThinking.tsx	Added Idle/Talking/Thinking wrapper components that render MascotCharacter with fixed pose props; Thinking computes loop-aligned think-in/out timing from useVideoConfig.
Remotion Mascot Lib: Thinking Timing remotion/src/Mascot/lib/MascotCharacter.tsx	Extended exported MascotCharacter props with ThinkingTiming (seconds-based thinkInStartSec, thinkInEndSec, thinkOutStartSec, thinkOutEndSec) and replaced fixed thinking-frame math with configurable ramps/out-ramp conditional logic.
Remotion Thinking Variant Update remotion/src/Mascot/yellow-MascotThinking.tsx	Reworked to read fps/durationInFrames via useVideoConfig, compute total duration, and pass calculated think timing props to MascotCharacter for seamless looping.

Sequence Diagram

sequenceDiagram
    participant HumanPage
    participant YellowMascot
    participant Selector as variantForFace
    participant Player as Remotion Player
    participant Variant as Variant (Idle/Talking/Thinking)
    participant MascotCharacter
    participant Face as Face (Normal/Loading/Recording)

    HumanPage->>YellowMascot: render(face)
    YellowMascot->>Selector: choose variant & inputProps
    Selector-->>YellowMascot: component + inputProps
    YellowMascot->>YellowMascot: memoize selection
    YellowMascot->>YellowMascot: useEffect -> player.play()
    YellowMascot->>Player: render Player(component, inputProps, fps, duration)
    Player->>Variant: mount variant
    Variant->>MascotCharacter: pass pose & timing props
    MascotCharacter->>MascotCharacter: compute frame-driven animations (bob, blink, mouth, thinking)
    MascotCharacter->>Face: render appropriate face overlay
    Face-->>MascotCharacter: composed SVG
    MascotCharacter-->>Player: rendered frame
    Player-->>YellowMascot: looping frames
    YellowMascot-->>HumanPage: displays animated mascot

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• tinyhumansai/openhuman#1147: Modifies mascot face/state logic and useHumanMascot usage; relates to replacing Ghosty and variant wiring.
• tinyhumansai/openhuman#1193: Extends yellow mascot variants and modifies MascotCharacter thinking timing in the Remotion mascot library.

Poem

🐰 I hopped in softly, yellow and bold,
SVG ears and stories told.
Bobbing, blinking, looping fine,
Remotion rhythms—dance in time.
A tiny rabbit cheers: "Hello, new mascot shine!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(mascot): swap to yellow mascot via @remotion/player' directly corresponds to the PR's main objective of replacing the Ghosty mascot with the yellow mascot using @remotion/player.
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: 2

🤖 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/features/human/Mascot/yellow/MascotThinking.tsx`:
- Line 1: The file MascotThinking.tsx imports the entire React namespace but
only uses it for typing (React.FC); change to a type-only import to follow TS
guidelines—for example replace the default namespace import with a type import
(e.g., import type React from 'react' or import type { FC } from 'react') and
update the component signature to use the chosen type (React.FC or FC) so the
runtime React import is removed.

In `@app/src/features/human/Mascot/YellowMascot.tsx`:
- Line 2: The file imports React as a value but only uses it for types and
defines a type alias for Variant; split the import so hooks remain runtime
imports and React is imported as a type (e.g., add "import type React from
'react';" and keep "import { useEffect, useMemo, useRef } from 'react';"), and
replace the "type Variant = { ... }" alias with "interface Variant { ... }" to
match repository conventions (this affects usages of React.FC and
React.ComponentType which will now reference the imported React type and the
renamed Variant interface).

🪄 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: 4697387e-3b4b-47a7-b485-fcee46a60ec7

📥 Commits

Reviewing files that changed from the base of the PR and between 24019ed and 957a771.

⛔ Files ignored due to path filters (3)

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

📒 Files selected for processing (12)

• app/package.json
• app/src/features/human/HumanPage.tsx
• app/src/features/human/Mascot/YellowMascot.tsx
• app/src/features/human/Mascot/index.ts
• app/src/features/human/Mascot/yellow/LoadingFace.tsx
• app/src/features/human/Mascot/yellow/MascotCharacter.tsx
• app/src/features/human/Mascot/yellow/MascotIdle.tsx
• app/src/features/human/Mascot/yellow/MascotTalking.tsx
• app/src/features/human/Mascot/yellow/MascotThinking.tsx
• app/src/features/human/Mascot/yellow/RecordingFace.tsx
• remotion/src/Mascot/lib/MascotCharacter.tsx
• remotion/src/Mascot/yellow-MascotThinking.tsx