---
schema_version: 1
id: RAC-KV01S1YHDPB1
type: roadmap
---
# RAC v0.8.12 — Explorer Mascot Interaction

## Status

Planned

## Context

The v0.8.7 visual overhaul gave the Explorer mascot its identity and its
animations: a hooded lantern-carrying guide with six state-driven frame
sequences (DESIGN-mascot, DESIGN-mascot-animations). One design for the
mascot remains unbuilt. DESIGN-mascot-interaction describes optional, opt-in
moments — selecting the mascot returns a small acknowledgement, occasional
discovery messages, gentle workflow guidance, and a rare easter egg — that
reward curiosity without ever interrupting work.

Today the mascot is a non-focusable `Static`; it cannot be selected, and
none of these responses exist. This milestone adds them, behind a new
preference, so the mascot becomes lightly interactive while staying identity,
never a feature: it gates nothing, hides nothing, and modifies nothing
(DESIGN-mascot-interaction, ADR-015).

## Outcomes

- Selecting the mascot — by mouse click or keyboard focus then Enter —
  returns a small, inline acknowledgement, so the interface rewards
  curiosity without a popup, a dialog, or a notification.
- Repeated selection surfaces occasional discovery messages, workflow
  guidance that points at existing commands, and one rare response — none
  of which unlock features or change the repository.
- Mascot interaction is independently disableable, alongside the existing
  mascot and animation toggles, so a user can turn it off without losing any
  RAC functionality.

## Initiatives

### Initiative 1 — Interaction Responses

The mascot's responses live as data and one pure function in
`rac.explorer.mascot` (textual-free, ADR-015): a default acknowledgement
("Still exploring."), three rotating discovery messages ("Context
preserved." / "Future teams will thank you." / "Remember why it changed."),
workflow guidance that names existing commands ("Try: /inspect
/relationships /health" — the mascot surfaces functionality, it does not
contain it), and a rare response ("You found the lantern.") reached only on
repeated selection. The response for the Nth selection is deterministic, so
it is fully unit-testable without a terminal.

### Initiative 2 — A Selectable Mascot

The home view's mascot becomes focusable and clickable: Enter or a click
appends the next response beneath the current figure — inline, never a
popup or a blocking dialog (DESIGN-mascot-interaction). It carries no
functionality of its own and reveals no hidden features. Selection works
whether or not animations are enabled (reduced motion) and the response is
plain widget text (screen readers, ADR-028).

### Initiative 3 — Optional Presence

A new `mascot_interaction` preference (default on) sits beside `mascot` and
`animations` in the preferences file and the `/settings` cycle. With it off,
the mascot is inert — not focusable, selection is a no-op — and every other
behaviour is unchanged. The three switches are independent: a user may keep
the mascot and its animation while turning interaction off, or any other
combination, and the Explorer stays fully functional in all of them.

## Implementation Contract

The following decisions are pinned for v0.8.12.

### Responses

- `rac.explorer.mascot` gains response data (`ACK`, `DISCOVERY_MESSAGES`,
  `GUIDANCE`, `RARE`, `RARE_AT`) and `interaction_message(count: int) -> str`:
  a pure, deterministic mapping from the 1-based selection count to a
  response — the rare line at exactly `RARE_AT`, guidance on a fixed cadence,
  the acknowledgement first, and the discovery messages rotating otherwise.
  No Textual import, no randomness.

### Widget

- The home view's `#mascot` becomes a small `Static` subclass that is
  focusable only while `preferences.mascot_interaction` is true; `on_key`
  (Enter) and `on_click` increment a per-widget selection counter and
  redraw the figure with the response appended on its own line. The
  animation tick keeps cycling the art; the response persists until the
  mascot state changes. No new screens, no modal, no notification.

### Preference

- `rac.explorer.preferences.Preferences` gains `mascot_interaction: bool =
  True`, round-tripped through `load_preferences`/`save_preferences` with the
  same bool tolerance as `mascot` and `animations`. `/settings` lists it and
  cycles it. An old preferences file without the key loads the default.

### Scope

- No Core or service changes, no new dependencies, no new commands. The
  mascot continues to appear only in the welcome and empty states
  (DESIGN-mascot); interaction is available wherever the mascot is shown.
  `adapter.py`, `state.py`, and `commands.py` are unchanged.

## Non-Goals

- Any functionality reached only through the mascot (DESIGN-mascot-interaction
  forbids hidden features).
- Popups, blocking dialogs, or notifications.
- Mascot presence outside the welcome and empty states.
- Changing existing key semantics or the mascot's animation behaviour.

## Success Measures

- Selecting the mascot (click or focus + Enter) shows a response inline with
  no popup, dialog, or notification.
- Repeated selection reaches the discovery messages, the guidance line, and
  the rare response, and none of them unlock a feature or touch the
  repository.
- With `mascot_interaction` off, the mascot is not focusable and selection
  does nothing, while the rest of the Explorer behaves exactly as before.
- `mascot.py` still imports no Textual (the isolation battery stays green).

## Assumptions

- The mascot remains a welcome/empty-state element (DESIGN-mascot); no view
  outside the home view needs to host it.
- Single-letter and `/` key semantics are unaffected because the mascot
  handles only Enter and click while focused.

## Risks

- Interaction competing with the animation timer: the response is held in a
  small field the tick respects, so cycling art never erases the message.
- Focus stealing: the mascot is focusable only when interaction is enabled
  and never grabs focus on its own, so keyboard-first navigation is
  unchanged.

## Related Decisions

- ADR-015
- ADR-019
- ADR-028

## Related Designs

- explorer-mascot
- explorer-mascot-interaction

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.7 explorer visual overhaul and mascot animations
