oikos/plans/2026-07-20-desktop-mascot.md

2026-07-20 — Desktop mascot ("Cluck")

Status: Implemented

Deviations from the original plan, applied 2026-07-20 during implementation:

• Hatching is no longer timed. The egg → chick transition fires once, on first naming (the name dialog opens on first mount of a fresh egg; submitting it calls forceHatch()). HATCH_MS is gone, tickLifecycle no longer advances hatchProgress, and the egg no longer plays a progressive egg-crack animation — it sits on egg-idle until named. hatchProgress is retained as a binary 0/1 flag so advanceStageIfReady() and the debug "Force hatch" action still work.
• Sprite art is PNG-sheet-based, not code-drawn pixel grids. The chicken comes from a CC0 16x16 sprite-sheet pack at web/public/mascot/; the egg comes from the Onocentaur egg pack (also CC0). palette.ts was removed; render.ts slices 16x16 frames from sheets instead of painting string grids. Chick and adult share sheets (distinguished only by render scale) until distinct adult art is added.
• The radial menu is a rounded-button column, not a circular ring. The plan's polar-layout ring was found to hide labels; the menu now mirrors the desktop's own right-click menu styling (full-text buttons, nested via a "Back" breadcrumb).
• The sprite loop runs at ~60fps (16ms setTimeout), not 30fps. Drag and fall motion at 30fps looked choppy on 60Hz+ displays. The setTimeout-not-rAF convention is preserved; dt is still clamped to 100ms. Position is applied via transform: translate3d
  • will-change: transform (compositor layer) instead of CSS left/top to avoid per-frame layout reflow.
• Egg-stage reactions are suppressed. The stimulus bus still subscribes to chat/activity/events while the egg is on screen, but MascotLayer's emit callback drops any reaction when model.stage === 'egg' — the egg isn't "alive" yet, so playing alarm/eureka animations behind the naming dialog would be jarring.
• The mascot walks on top of windows. The ground line is recomputed each tick from wmState: it's the top edge of the highest non-minimized window whose horizontal span covers the mascot's x, or the surface bottom when no window is beneath. When the mascot strolls over a window, the ground rises to that window's top edge; when it walks off the side, the ground drops and it flutter-falls to the next surface beneath (another window, or the desktop). This generalizes the original "walks along the desktop surface's bottom edge" decision to a multi-surface model.

Why

The web control room is an OS-style desktop shell (icons, floating windows, taskbar) but has no ambient, always-visible signal of what the system is doing — you have to open a window to see a chat streaming, a knowledge-graph write, or a critical signal land. The user asked for a pixel-art chicken mascot that roams the desktop, is draggable and interactable (Sims-style radial right-click menu with nested actions), and is itself a tamagotchi (egg → chick → adult, nameable, persistent) that visibly reacts to real app activity. This plan is scaffolding: every piece (sprites, autonomous behaviors, menu actions, environment reactions) is a data-driven registry so each can be extended independently later without touching the engine code.

The MBSE subsystem model for this feature (Mission, Requirements, Structural/Behavioral/Interfaces views, Verification) lives at docs/mascot/README.md — read it first for the full rationale and diagrams; this document is the concrete file-by-file implementation plan derived from it.

Design decisions already made with the user:

• Renders above windows (desktop-pet style) — mascot layer z-45, radial menu z-[60] (must beat the desktop's own right-click menu, which is z-50).
• Art is code-drawn pixel art — string pixel-grids + a palette map in TypeScript, rendered to a small canvas, no binary sprite assets.
• Movement is gravity + ground — walks along the desktop surface's bottom edge (= the taskbar's top edge), flutter-falls when dropped mid-air.

Verified codebase facts this plan builds on

• web/src/lib/components/desktop-shell/Desktop.svelte — the surface div (relative min-h-0 flex-1 overflow-hidden) hosts layered children: icon layer z-0, TaskLauncher wrapper z-10, WindowLayer z-40 — every wrapper is pointer-events-none with interactive children re-enabling pointer-events-auto. The desktop's own right-click menu is fixed z-50, dismissed via <svelte:window onclick={closeMenu}> + Escape. Bare-surface clicks are gated with e.currentTarget === e.target.
• Drag pattern to copy: desktop-shell/DesktopIcon.svelte — pointerdown + el.setPointerCapture(e.pointerId), a 5px movement threshold distinguishes a click from a drag, move/up listeners attached to the element itself (not window), position blended via $derived between rest and drag-in-progress values.
• Game loop convention: GraphBackground.svelte drives its canvas with setTimeout(() => draw(performance.now()), 33) (~30fps), not requestAnimationFrame — the code comment there explains some embedding contexts report document.hidden=true and suspend rAF, which would freeze the animation; setTimeout keeps ticking. Follow this for the mascot loop, and clamp dt to 100ms so a throttled/backgrounded tab doesn't produce a physics-breaking huge step on resume.
• Persistence convention: hyphenated oikos-* localStorage keys (oikos-desktop-icons, oikos-theme, oikos-windows). Window layout uses wmkit's persist(wm, { key: 'oikos-windows', debounce: 300, autoRestore: true }) — mirror the 300ms debounce for oikos-mascot; never write on every animation frame, only on discrete state transitions (behavior change, drag end, stage change, rename).
• Runes idiom for cross-component client state: a .svelte.ts module with module-level $state plus exported getter/mutator functions — web/src/lib/stores/theme.svelte.ts is the canonical example (let current: Theme = $state(initialTheme), getTheme(), setTheme(), toggleTheme()).
• Awareness sources, all plain Svelte stores already in the codebase:
  • web/src/lib/stores/events.ts — liveEvents: Writable<OikosEvent[]> (newest-first, capped at 200), fed by a ref-counted SSE subscription subscribeEvents(). OikosEvent.type families: approval.*, signal.*, execution.*, health.changed; severity: 'info' | 'warning' | 'critical'.
  • web/src/lib/stores/chat.ts — streaming: Writable<boolean>.
  • web/src/lib/stores/activity.ts — activityLog is a derived store recomputed wholesale from messages/planSteps/currentTask on every emission, not an append-only log — detecting a "new" entry (e.g. type === 'knowledge') requires diffing entry ids against the previous emission, not just reacting to the store firing.
  • web/src/lib/stores/context.ts — summary: Writable<DashboardSummary | null>, openSignalCount(summary).
• No @keyframes, no requestAnimationFrame, no sprite/pixel-art code exists anywhere in the repo today — this is greenfield within the established canvas-loop convention above.

File layout

All new, under web/src/lib/mascot/:

types.ts            PixelGrid, AnimName, MascotStage, BehaviorId, Stimulus, RadialAction
palette.ts           Record<char, cssColor>; '.' = transparent
sprites.ts            SPRITES: Record<MascotStage, Partial<Record<AnimName, AnimDef>>> + resolveAnim() fallback
render.ts             drawFrame(ctx, grid, palette, flip) — stateless canvas painter
state.svelte.ts       Tamagotchi model: module $state + mutators, debounced persist, versioned schema
behavior.ts           FSM: BEHAVIORS registry + stepMascot(rt, model, now, dt)
stimuli.ts            Stimulus bus: REACTIONS registry + attachStimuli(emit), ref-counted
actions.ts            MASCOT_ACTIONS radial tree + registerMascotAction()
Mascot.svelte         canvas sprite, 30fps loop, pointer drag/click/contextmenu
MascotLayer.svelte    pointer-events-none absolute inset-0 z-45 overlay; hosts Mascot + RadialMenu + bubble
RadialMenu.svelte     round nested menu, fixed z-[60]
NameDialog.svelte     naming prompt (hatch + rename)

Integration — 2 lines in Desktop.svelte: import MascotLayer and render <MascotLayer /> inside the surface <div>, after <WindowLayer />, so its absolute inset-0 shares the surface's coordinate space and its ground line lands exactly at the surface's bottom edge (the taskbar's top edge).

Sprite system (types.ts, palette.ts, sprites.ts, render.ts)

Frames are human-editable string pixel-grids indexing a palette, e.g.:

export type PixelGrid = string[]   // rows of same-length strings, one char per pixel
export interface AnimDef { frames: PixelGrid[]; fps: number; loop: boolean }
export type AnimName =
  | 'egg-idle' | 'egg-wiggle' | 'egg-crack' | 'hatch'
  | 'idle' | 'blink' | 'walk' | 'peck' | 'flap' | 'sleep'
  | 'dragged' | 'fall-flutter' | 'land'
  | 'react-eureka' | 'react-alarm' | 'react-think' | 'react-happy'

• Grids: egg 12×12, chick 14×14, adult 16×16, all bottom-anchored inside a fixed 20×20 logical canvas so feet land on the ground line consistently across stages.
• SPRITES: Record<MascotStage, Partial<Record<AnimName, AnimDef>>> is the registry; resolveAnim(stage, name) falls back to that stage's idle and finally a 1-frame placeholder, so a missing animation never crashes the renderer.
• Canvas is sized to the logical grid; screen scale is pure CSS (width: 20*SCALE px; image-rendering: pixelated), ctx.imageSmoothingEnabled = false set once. Horizontal facing flip via ctx.translate(w,0); ctx.scale(-1,1) — no mirrored frame data needed.
• Initial animation set (2–4 frames each): egg-idle/egg-wiggle/egg-crack/ hatch; idle/blink/walk/peck/flap/sleep; dragged/fall-flutter/land; react-think/react-eureka/react-alarm/react-happy.
• Frame index = floor((now - animStart) / 1000 * fps), wrapped if loop.

Behavior engine (behavior.ts)

export interface MascotRuntime {
  x: number; y: number            // sprite bottom-center, surface coords
  vx: number; vy: number
  facing: 1 | -1
  behavior: BehaviorId            // 'egg' | 'idle' | 'wander' | 'peck' | 'sleep' | 'dragged' | 'falling' | 'react'
  behaviorUntil: number
  anim: AnimName
  animStart: number
  reactAnim: AnimName | null
  bounds: { w: number; h: number }
}

export interface BehaviorDef {
  id: BehaviorId
  anim: (rt: MascotRuntime, model: MascotModel) => AnimName
  enter?: (rt: MascotRuntime) => void
  tick: (rt: MascotRuntime, dt: number, now: number) => void
  next: (rt: MascotRuntime, now: number) => BehaviorId | null
  weight?: number         // idle-selectable when > 0; undefined/0 = not auto-picked
  minMs: number; maxMs: number
}
export const BEHAVIORS: Record<BehaviorId, BehaviorDef>
export function stepMascot(rt: MascotRuntime, model: MascotModel, now: number, dt: number): void
export function forceBehavior(rt: MascotRuntime, id: BehaviorId, opts?: { anim?: AnimName; durationMs?: number }): void

• Ground/gravity: GROUND_Y = bounds.h. When above ground and not dragged, behavior is falling: vy += GRAVITY * dt, capped at a slow flutter terminal velocity, anim fall-flutter with occasional flap; on reaching ground, snap y, brief land, then idle.
• Wander: constant vx = facing * ~40px/s, flip facing at the surface margins.
• Idle selection: when now > behaviorUntil and the current behavior's next() returns null, roll a weighted random pick over BEHAVIORS entries that declare weight — starting weights: idle 3, wander 4, peck 2, sleep 1.
• Non-self-selecting behaviors (dragged, falling, react) have no weight and are entered only via forceBehavior() — pointer code calls it for dragged, gravity logic for falling, the stimulus bus for react.
• Egg stage: behavior locked to 'egg' (renders egg-idle, wiggles gently via a render-time transform); dragging is still allowed (the egg can be picked up and moved). The egg → chick transition fires once, on first naming — see the deviation note at the top of this plan.
• Loop lives in Mascot.svelte: setTimeout(() => tick(performance.now()), 33) inside an $effect, cleared on teardown, dt clamped to 100ms.

Tamagotchi model (state.svelte.ts)

export type MascotStage = 'egg' | 'chick' | 'adult'
export interface MascotModel {
  version: 1
  stage: MascotStage
  name: string | null
  hatchProgress: number       // binary 0/1: 0 until first naming, 1 after (egg stage only)
  happiness: number           // 0..100, slow decay, boosted by pet/feed
  xp: number                  // chick -> adult growth hook
  hatchedAt: number | null
  lastPos: { x: number } | null
  lastSeen: number            // for capping passive decay
}
export const ADULT_XP = 200
export function grantXp(n: number): void
export function feed(): void
export function pet(): void
export function setName(name: string): void
export function tickLifecycle(dt: number): void   // called ~1x/sec, not per frame
export function advanceStageIfReady(): void
export function forceHatch(): void                 // called by the name-dialog submit handler on first naming

• load() parses localStorage['oikos-mascot'], checks version, falls back to defaultModel() on mismatch/corruption. migrate(raw): MascotModel is a stub switch on version for future schema changes — v1 has no migrations to perform, the stub just documents where they go.
• Every mutator calls a shared schedulePersist() — a 300ms trailing debounce, plus a beforeunload flush so a quick reload doesn't lose a rename. lastPos.x is written only on behavior transitions and drag-end, never per frame.
• The egg → chick transition is not timed: a fresh egg (stage=egg, name=null) opens the name dialog on mount; submitting it calls forceHatch() which sets hatchProgress=1 and setStage('chick'). Returning users with a named mascot skip the dialog. See the deviation note at the top of this plan.
• Multi-tab races (two tabs both writing oikos-mascot) are last-writer-wins — accepted for this scaffolding, not solved; a future pass could listen to the storage event if it becomes a real problem.

Radial menu (actions.ts, RadialMenu.svelte)

export interface RadialAction {
  id: string
  label: string
  icon?: Component                          // lucide, same convention as the desktop menu
  visible?: (model: MascotModel) => boolean // e.g. Rename only once hatched
  children?: RadialAction[]
  action?: (ctx: MascotActionCtx) => void   // leaf only
}
export const MASCOT_ACTIONS: RadialAction[]
export function registerMascotAction(a: RadialAction, parentId?: string): void

v1 tree: Interact [Pet, Feed → [Seeds, Worm]], Care [Sleep, Wake], Identity [Rename], Debug [Force hatch/stage, Reset].

• Rendered by MascotLayer.svelte as fixed, positioned at the chicken's screen center, z-[60] (must beat the desktop context menu's z-50, comfortably above WindowLayer's z-40).
• Layout: items on a circle (radius ≈ 70px) via polar transforms around the menu's anchor point. Open animation: buttons start scale-0 at center and transition to their polar position with transform 120ms cubic-bezier(.2,1.4,.4,1), staggered ~20ms per item — pure CSS, no keyframes, reads as snappy/springy per the "snappy" requirement.
• Nesting: selecting a node with children swaps the ring's contents to those children plus a center "back" button; track the breadcrumb as a local $state<RadialAction[][]> stack.
• Dismissal mirrors the desktop menu's existing pattern: <svelte:window onclick={close}>, Escape pops one level then closes on the next press; the menu's own clicks stopPropagation(). Clamp the ring's screen position so it never renders off-viewport (relevant near screen edges/corners).
• Opened from Mascot.svelte's oncontextmenu: e.preventDefault(); e.stopPropagation(); then tell MascotLayer to open at the sprite's center (the surface's own onSurfaceContextMenu already gates on currentTarget === target, so this is defensive, not strictly required — but keep it for clarity).

Stimulus / reaction system (stimuli.ts)

export interface ReactionDef {
  id: string
  anim: AnimName
  priority: number
  cooldownMs: number
  durationMs: number
  interruptsSleep?: boolean
  effect?: () => void          // e.g. grantXp(5) on eureka
}
export const REACTIONS: Record<string, ReactionDef>
export function attachStimuli(emit: (r: ReactionDef) => void): () => void   // ref-counted, owns subscribeEvents()

Initial wiring:

Source	Trigger	Reaction
chat.ts streaming	false → true edge, held while true	thinking (react-think, priority 1)
activity.ts activityLog	new entry with type === 'knowledge', detected by diffing entry ids against the last-seen set (see note above — the store is recomputed wholesale)	eureka (react-eureka, priority 2, cooldown 10s, effect: grantXp(5))
events.ts liveEvents	new head event (id > lastSeen) with severity === 'critical' or type starting signal.	alarmed (react-alarm, priority 3, cooldown 15s, interruptsSleep: true)
events.ts liveEvents	new head event, type starting execution., success-ish	happy (react-happy, priority 1, cooldown 20s)

• attachStimuli calls subscribeEvents() itself and folds its unsubscribe into the returned teardown, so the mascot keeps the SSE stream open (ref-counted alongside any page that also subscribes) only while mounted.
• Egg-stage reactions are suppressed. MascotLayer's stimulus callback drops any reaction when model.stage === 'egg' — the egg isn't "alive" yet (no name, no hatched chick to react), so stimulus events are silently ignored until the egg hatches. This keeps the egg calm during the naming dialog rather than playing alarm animations behind it.
• On first emission of liveEvents, just record the head event id — do not replay history as reactions on mount.
• Dispatch: emit(reaction) checks the cooldown map and priority >= currentReactPriority (or current behavior isn't dragged), then calls forceBehavior(rt, 'react', { anim, durationMs }). dragged always wins over any reaction; sleep is broken only when interruptsSleep is true.

Implementation order (sized for one PR each)

1. types.ts, palette.ts, sprites.ts (egg + chick idle/walk only), render.ts — pure data/functions, no UI yet.
2. state.svelte.ts model + debounced persistence — verify by hand via devtools console before wiring any UI.
3. behavior.ts FSM (egg/idle/wander/falling/dragged) + Mascot.svelte + MascotLayer.svelte, insert into Desktop.svelte. First visible milestone — an egg sits on the ground and can be dragged.
4. Hatch flow: tickLifecycle wired into the loop, egg→chick transition + NameDialog.svelte, remaining animations, peck/sleep behaviors.
5. actions.ts + RadialMenu.svelte (nested rings, open animation, dismissal).
6. stimuli.ts + the four reaction animations + the wiring table above.
7. Adult stage sprites + XP threshold; polish (speech/name bubble, a squash frame on land).
8. A short "how to add an animation / behavior / action / reaction" doc comment at the top of sprites.ts, behavior.ts, actions.ts, and stimuli.ts respectively (this plan's registry tables above become those comments, condensed).

Verification checklist

Run npm run dev in web/, then in the browser:

• Egg renders on the ground at the surface bottom, wiggles occasionally, and is at the same x after a reload (oikos-mascot in localStorage — confirm it is not being written on every frame while merely idling or walking, only on discrete transitions).
• Dragging the egg up and releasing triggers a flutter-fall back down with no tunneling below the taskbar; dragging past the surface's left/right edges clamps rather than escaping the viewport.
• The debug "force hatch" action transitions egg → chick, opens the name dialog, and the chosen name persists across a reload.
• The chick wanders and flips its sprite at the surface edges, pecks, and sleeps on its own; a plain click (below the 5px drag threshold) triggers a pet/hop reaction and grants a little xp.
• Right-clicking the chicken opens the radial menu centered on it — and right-clicking bare desktop elsewhere still opens the original desktop menu, unaffected. The nested Feed submenu opens; Escape pops one level then closes on the next press; clicking outside the menu closes it; the menu stays fully on-screen when the chicken is near a corner.
• With a maximized window open, the chicken visibly walks above it; window drag/resize/close still work normally when the chicken merely passes under the cursor (not when it's directly over a button being clicked — known, accepted overlap per the "renders above windows" decision).
• Sending a chat message and watching it stream triggers the thinking animation for the duration; simulate (or trigger for real) a knowledge-graph write and confirm eureka fires once and respects its cooldown on a second write; simulate a critical signal and confirm alarmed fires even while the chicken is asleep.
• Resizing the browser viewport re-grounds the chicken and keeps it within the new bounds.
• Both the Terracotta and Carbon themes keep the pixel palette legible.
• npm run build passes with no new errors or warnings beyond the pre-existing baseline.

Risks

• Z-index ordering is easy to get subtly wrong: radial menu must be z-[60] to beat the desktop context menu's z-50; the mascot layer itself is z-45 (above WindowLayer's z-40, below both menus).
• The mascot rendering above windows means it can occlude/steal clicks on window chrome directly beneath it — accepted per the "above windows" decision; mitigate by keeping the pointer hitbox tight to the canvas element only (no oversized invisible padding).
• activityLog is a derived store recomputed wholesale on every emission, not an append-only log — any "new entry" detection must diff entry ids between emissions, never assume the store only ever grows by appending.
• setTimeout-driven loops can receive large dt spikes after tab throttling/backgrounding resumes — clamp dt before feeding it into physics or lifecycle ticking.