Add reactive on-screen mascot (DMarcus-style)

[schmug]

Goal

Add an on-screen avatar to CortechOS, similar to DMarcus (the themed mascot on dmarc.mx) — reactive to what's happening on the page. Could reuse DMarcus directly or design a cortech-palette sibling.

Reference

DMarcus has states like: building, scared, sleeping, thinking, etc. He's page-color-themed (adapts when the theme switches).

Desktop placement ideas

• Small (64–96px) animated sprite anchored to the bottom-right of the desktop area, above the taskbar.
• Doesn't intercept clicks, doesn't land in the window-manager z-stack.
• Optional "click to pet" interaction that cycles through a couple of easter-egg states.

Reactive states (initial set)

• idle / building — default loop
• sleepy — after ~60s of no interaction (mousemove/keydown)
• excited — when a window opens
• scared — when a window is dragged off-screen or force-closed (Cmd+W)
• proud — when the Support app opens or a sponsor link is clicked

Implementation sketch

• src/components/os/Mascot.tsx as a small React component, subscribed to the zustand store for state transitions.
• Sprite: either a multi-frame SVG with CSS keyframes, or a spritesheet. Respect prefers-reduced-motion — reduce to a static pose.
• If reusing DMarcus, extract the sprite from the dmarc.mx repo; re-theme palette via CSS variables so the cortech colors (amber/cyan/hot on void background) apply naturally.

Acceptance

• Avatar renders on desktop; does not render on mobile (MobileShell).
• At least 2 state transitions are visible in normal use (e.g. idle → excited on window open).
• Respects prefers-reduced-motion: reduce (static pose, no animation).
• Click interaction is unobtrusive (no modal, no focus steal).

Additional reactive state (added 2026-04-13)

• dizzied — pseudo-LLM "tokens" rain in from above and bounce off the mascot; after enough hits (or 3 windows opened in <1.5s) the mascot wobbles with stars circling its head for ~3s, then returns to idle. See research comment for design.

[schmug]

Implementation research

Sanity-checked against main at 2410363 — npm run test (15 ✅), npm run typecheck (0 errors), npm run test:e2e (3 ✅) all pass before this work starts.

Current shell — touch points

• Zustand store: src/components/os/store.ts:47. Window-lifecycle actions here are the natural dispatch surface for mascot reactions:
  • openApp (line 55) → excited
  • closeWindow (line 96) → check if window was off-screen / force-closed (Cmd+W) → scared
  • focusWindow (line 107), minimizeWindow (line 121) → optional micro reactions
• Idle detection: not present today. Add a useIdleTimer hook (mousemove/keydown/scroll, 60s) inside OSShell.tsx that calls a new setMascotState('sleepy') action.
• Reduced motion: already globally short-circuited in src/styles/global.css:54. New mascot CSS should additionally provide a static pose under @media (prefers-reduced-motion: reduce) so the character renders but doesn't move.
• Mobile: don't render. RootShell.tsx already swaps to MobileShell under 768px — Mascot mounts inside OSShell only, so this is automatic.

Mascot component shape

src/components/os/Mascot.tsx (new):

type MascotState =
  | 'idle' | 'building' | 'sleepy' | 'excited'
  | 'scared' | 'proud' | 'dizzied';

// Subscribes via useOS((s) => s.mascotState).
// Renders a fixed-position div in the bottom-right of the desktop area,
// above the taskbar (z-index between desktop and window stack, but
// pointer-events: none except on the inner clickable hitbox).

Anchor: position: absolute; right: 24px; bottom: calc(var(--ct-taskbar-h) + 24px). Render inside OSShell (not in WindowManager) so it lives outside the window z-stack.

Store extensions

Add to OSState in store.ts:

mascotState: MascotState;
mascotReason: string | null;        // for debug + e2e selectors
setMascotState: (s: MascotState, reason?: string) => void;
// Optional: auto-revert helper that schedules state → 'idle' after Nms.

Do not persist mascotState (add to the partialize exclusion list) — it should always boot as idle.

Sprite — port DMarcus, repaint with cortech palette

DMarcus in schmug/dmarcheck is a pure-CSS creature, no images. Port the anatomy verbatim:

• <div class="mascot-body">@<div class="mascot-eyes">…</div></div>
• <div class="mascot-legs">×3</div> (three legs, alternating heights via keyframes)

Source to mirror:

• src/views/components.ts::generateCreature(size, mood, partyHat?) — DOM template
• src/views/styles.ts — creature-* keyframes (creature-walk, creature-panic, creature-chomp) and mood classes (creature-celebrating, creature-content, creature-worried, creature-scared, creature-panicked)

Recolor via cortech tokens (defined in src/styles/global.css:8):

• Body / legs: var(--color-amber) (#f6c34a) — DMarcus is #f97316, ours is the warmer cortech amber
• Eye whites: var(--color-text) (#f2efe6)
• Pupils: var(--color-void) (#0b0d12)
• Hot accent for the dizzied stars: var(--color-hot) (#ff6a5c)

Mood ↔ state mapping reuses dmarcheck classes where possible:

State	DMarcus class	Trigger
idle	creature-content	Default
building	creature-content	(alias of idle for now; specialise later)
sleepy	new mascot-sleepy	60s of no mousemove/keydown
excited	creature-celebrating	openApp
scared	creature-scared	Window dragged off-screen or force-closed (Cmd+W)
proud	creature-celebrating + party hat	Support app opened or sponsor link clicked
dizzied	new — see below	"AI token" rain hit threshold or rapid window-spam

New state: dizzied — "AI tokens rain on the mascot"

Concept: small pseudo-LLM tokens fall in from above the screen, fall under gravity, hit the mascot's hitbox, and bounce off. After N hits the mascot flips to dizzied: little stars (✦) circle its head, body wobbles. After ~3s it returns to idle.

Token vocabulary (text-only, no emoji — fits the builder aesthetic):

the, of, and, </s>, <|im_start|>, [CLS], [SEP], 0xFA, ▁the, ▁tok,
GPT, attn, kv, λ, ∇, log p

Random pick per particle. Render in var(--font-mono), 11px, var(--color-cyan) with 60% opacity.

Particle system

src/components/os/TokenRain.tsx — sibling of Mascot.tsx, rendered by Mascot.tsx while mascotState !== 'sleepy'.

type Token = {
  id: number; text: string;
  x: number; y: number;
  vx: number; vy: number;
  rot: number; vrot: number;
  life: number;
};

• Pool capped at 30 particles. Reuse slots via a free list — no GC churn.
• Spawn cadence: 1 token / 250–600ms while a "shower" is active. Showers are triggered by:
  1. Ambient timer — every 90–180s (random) when desktop is interactive; burst of 8–14 tokens.
  2. Window-spam heuristic — opening 3 windows within 1.5s triggers a shower immediately (lampshades the "you're overwhelming me" vibe).
  3. Click the mascot — easter-egg burst on demand (also covers the "click to pet" mention in the issue body).
• Single shared RAF loop in a useEffect. Update positions: vy += GRAVITY * dt; x += vx * dt; y += vy * dt; rot += vrot * dt. Apply via transform: translate3d(x, y, 0) rotate(rot) for compositor-only updates.
• Collision: AABB check between each token and mascotRectRef.current (cached getBoundingClientRect, refreshed on resize). On hit:
  • Flip token's vy (×−0.55), nudge vx outward, increment hitCount.
  • Particle keeps falling and fades over ~600ms (life).
• Threshold: hitCount >= 5 within 4s → call setMascotState('dizzied', 'token-overwhelm'). Schedule revert to idle in 3s (setTimeout, store the handle, clear on unmount).

Dizzied visuals (CSS only):

@keyframes mascot-wobble {
  0%, 100% { transform: rotate(-6deg); }
  50%      { transform: rotate(6deg); }
}
@keyframes mascot-stars {
  to { transform: rotate(360deg); }
}
.mascot-dizzied .mascot-body { animation: mascot-wobble 0.45s ease-in-out infinite; }
.mascot-dizzied::after {
  content: "✦  ✦  ✦";
  position: absolute;
  inset: -18px 0 auto 0;
  font: 10px var(--font-mono);
  color: var(--color-hot);
  letter-spacing: 4px;
  transform-origin: 50% 22px;
  animation: mascot-stars 1.2s linear infinite;
}

Reduced motion contract: under prefers-reduced-motion: reduce, TokenRain renders nothing (early return) and the dizzied state shows a static ?_? glyph next to the mascot for 1.2s instead of wobble + stars.

Performance budget: 30 particles × transform updates per frame is trivially under the budget (≈0.1ms/frame in profiling on similar setups). RAF loop pauses itself when document.visibilityState === 'hidden' and when no shower is active.

Acceptance criteria — additions to the original issue

In addition to the criteria already in the issue body:

• dizzied state plays after a window-open burst (open 3 apps in <1.5s) and after the random ambient shower fires.
• Token particles are pooled (no allocations after warmup) and capped at 30 alive at once.
• Under prefers-reduced-motion: reduce: no token rain, no wobble, static ?_? hint for 1.2s on dizzied trigger.
• Mascot anchor is bottom-right of the desktop area, above the taskbar; never overlaps the launcher overlay (rendered with lower z-index than Launcher).
• Tokens never intercept pointer events (pointer-events: none on the rain layer).
• e2e: a Playwright test forces mascotState = 'dizzied' via a window.__cortechos.setMascotState('dizzied') test hook and asserts the wobble class is present on [data-testid="mascot"].

Test additions (vitest)

Extend src/components/os/store.test.ts:

• setMascotState updates state and reason.
• mascotState is not persisted (set state, reload via useOS.persist.rehydrate(), assert idle).
• Window-spam heuristic helper (extract pure function): given timestamps [t1, t2, t3], returns true iff all three are within 1500ms.

Suggested build sequence (≈5–7h)

1. Store: add mascotState, setMascotState, exclude from persist (~30m).
2. Mascot.tsx static port of DMarcus + cortech palette + idle/excited/scared/proud/sleepy moods wired (~2h).
3. Idle hook in OSShell (~30m).
4. TokenRain.tsx + RAF loop + pool + collision (~2h).
5. Dizzied state + wobble/stars CSS + threshold trigger + auto-revert (~1h).
6. Tests (unit + 1 Playwright assertion via test hook) (~1h).

Files to add / modify

New:

• src/components/os/Mascot.tsx
• src/components/os/TokenRain.tsx
• src/components/os/useIdleTimer.ts

Modify:

• src/components/os/store.ts — extend OSState with mascot fields, exclude from persist partialize.
• src/components/os/OSShell.tsx — mount <Mascot /> inside the desktop layer, attach idle timer.
• src/components/os/store.test.ts — coverage for new actions.
• e2e/smoke.spec.ts — assert mascot renders on desktop, not on mobile.

[schmug]

Research — DMarcus feeding minigame (supersedes the passive dizzied design above)

This is an alternative research path for the dizzied state. The prior comment's ambient rain + window-spam triggers are dropped; this design is the single path to dizzied/crash. Salvages the wobble+stars visual as the final beat before crash.

Mirrored in the repo at docs/superpowers/specs/2026-04-13-dmarcus-feeding-game-design.md.

---

Context

This research spec replaces the passive mechanic with an interactive virtual-pet minigame. DMarcus is sentient: he wanders and intermittently signals hunger by opening his mouth. While his mouth is open, any cursor movement sheds "AI tokens" that fall under gravity; tokens that land in his mouth count as a feeding and grow him slightly. After ~6 successful feedings he overflows, triggers a dizzied beat, glitches, and the whole "OS" fake-reboots via the existing BootSplash — without disturbing the user's open windows. Tokens that miss fade as debris.

Decisions locked in

#	Question	Choice
1	Relationship to existing dizzied research	Merge — minigame is the only path to dizzied/crash; ambient + window-spam triggers dropped
2	How tokens spawn from the cursor	Hunger-gated trail — cursor movement only sheds tokens while DMarcus's mouth is open
3	Hunger pacing	Intermittent — every 2–4 min, mouth open ~6s, subtle tell (open mouth + faint cyan glow)
4	Growth curve	Slow build — ~6 feedings → crash, scale 1.0 → 2.0 (80px → 160px), smooth CSS transition
5	Crash visual	Fake OS reboot, layout preserved — glitch → black → BootSplash replay → back to desktop; easter-egg overlay > recovered from mascot overflow
6	Persistence	Crash counter only — crashCount persisted via zustand; surfaced as a one-liner in AboutApp

State machine

idle ──(random 120–240s timer fires)────────────▶ hungry
hungry ──(no catch within 6s)────────────────────▶ idle            // missed feeding, no penalty
hungry ──(first caught token)────────────────────▶ feeding
feeding ──(1.2s without another catch)───────────▶ idle            // user stops feeding mid-meal; counts as completed if ≥1 token
feeding ──(hunger window ends OR user stops)─────▶ idle (feedingsThisLife++)
idle ──(feedingsThisLife === 6)──────────────────▶ stuffed         // checked on entry to idle
stuffed ──(1.8s wobble+stars)────────────────────▶ crashing
crashing ──(800ms glitch + black overlay)────────▶ rebooting
rebooting ──(BootSplash replay completes)────────▶ idle            // scale 1.0, feedings 0, crashCount++

Precedence vs sleepy (existing issue state): sleepy > hungry. Hunger timer does not fire while sleepy; on wake, the remaining hunger countdown resumes from where it was paused.

One "feeding" = one hunger window in which the user landed ≥1 token in the mouth. Per-feeding growth is a fixed step (≈0.167 scale units) so the 6th feeding always lands at scale 2.0.

Mechanics

Hunger timer

• On every entry to idle, schedule setTimeout(fire, uniform(120000, 240000)).
• Clear on unmount, explicit state override (test hook), crash sequence start, and sleepy entry.
• On fire: setMascotState('hungry'), open mouth sprite, attach faint box-shadow cyan halo.
• If no catch within 6000ms: revert to idle (no growth, no penalty).

Token trail (hunger-gated)

• TokenRain.tsx owns one shared requestAnimationFrame loop.
• Spawning gated: spawn only when mascotState === 'hungry' || 'feeding' AND a document mousemove fired in the last frame.
• Spawn cadence: one token per ≥80ms of cursor travel, capped at 30 live tokens (pooled).
• Token physics: vy += GRAVITY * dt; vx inherits 15% of cursor velocity, clamped; rotation drifts via vrot.
• Rendering: transform: translate3d(x, y, 0) rotate(rot) for compositor-only updates.
• Token vocabulary reused from prior comment: the, </s>, <|im_start|>, [CLS], [SEP], GPT, attn, kv, λ, ∇, log p, ▁tok, 0xFA. Mono 11px, var(--color-cyan) @ 60% opacity.
• pointer-events: none on the whole rain layer.
• RAF loop pauses when tab hidden and when no tokens are alive and mascot is not hungry/feeding.

Catch detection

• Mouth AABB ~18px × 12px, offset from body origin, recomputed on scale/resize.
• On token × mouth AABB intersection: token removed (caught), transition hungry → feeding, catchesThisWindow++.
• When hunger window closes with catchesThisWindow ≥ 1: recordFeeding() → feedingsThisLife++, mascotScale += 1/6, smooth transition: transform 400ms ease-out. At 6: schedule stuffed next tick.
• Uncaught tokens keep falling; fade out over 600ms after passing mascot bottom.

Crash + reboot orchestration

1. stuffed (1800ms): wobble + ✦ stars — reuse the dizzied keyframes from the prior comment.
2. crashing (400ms): CSS filter glitch on #ct-desktop (hue-rotate(20deg) contrast(1.3) + translate jitter); mascot fades to 0.
3. black overlay (200ms fade-in + 200ms hold): full-viewport var(--color-void) above everything except reboot text.
4. easter egg overlay during the hold: bottom-left, mono 11px cyan, > recovered from mascot overflow. Fades as BootSplash starts.
5. BootSplash replay: remount via key={rebootId}; flip hasBooted = false during reboot to let the existing component drive itself. Do not call resetLayout() — windows stay exactly where they were.
6. finishReboot: setMascotState('idle'), mascotScale = 1.0, feedingsThisLife = 0, crashCount++, reschedule hunger.

Accessibility

• prefers-reduced-motion: reduce:
  • No token rain (TokenRain early-returns).
  • Scale changes instant, no transition.
  • No glitch, no black overlay, no BootSplash replay — skip stuffed → idle with a brief static ?_? pose for 1.2s.
• Mascot hidden on mobile (automatic via RootShell's OSShell/MobileShell branch).

Store changes (src/components/os/store.ts)

type MascotState =
  | 'idle' | 'hungry' | 'feeding' | 'stuffed' | 'dizzied' | 'crashing' | 'rebooting';

// OSState additions:
// mascotState, mascotScale, feedingsThisLife, crashCount
// setMascotState, recordFeeding, beginReboot, finishReboot

// partialize allow-list so ONLY crashCount persists across reloads.

AboutApp surface

One line near the footer, only when crashCount > 0:

dmarcus has crashed this device {n} time{s}

Critical files

New: src/components/os/Mascot.tsx, src/components/os/TokenRain.tsx, src/components/os/useHungerTimer.ts, src/components/os/useIdleTimer.ts (sleepy detection), mascot.css or inline <style>.

Modify: src/components/os/store.ts, src/components/os/store.test.ts, src/components/os/OSShell.tsx, src/components/os/BootSplash.tsx (verify key-based remount), src/components/apps/AboutApp.tsx, e2e/smoke.spec.ts.

Verification

• Unit (vitest): state machine legal transitions, recordFeeding scale math, finishReboot reset + crashCount bump, persist allow-list, pure catch AABB fixture table.
• Playwright: mascot present on desktop / absent on mobile; forced stuffed → crashing → rebooting → idle via window.__cortechos test hooks asserts crashCount++ and open windows survive.
• Manual: npm run dev, leave tab focused ~3 min, watch for hunger tell, feed to crash, reload, confirm AboutApp counter. Toggle reduced-motion, repeat — no rain, no glitch, no replay.

Out of scope

• High-score / achievements / unlockable cosmetics.
• Touch variant of the minigame.
• Sound effects.
• Other mascot moods (excited, scared, proud, building) — covered by baseline issue work.
• Difficulty tuning UI.

Open implementation questions

• Whether BootSplash reboot uses key-based remount paired with a hasBooted flip, or a new force?: boolean prop. Pick the smaller change during writing-plans.
• Exact cursor-travel spawn cadence (80ms vs 120ms) — calibrate during playtest.