← All apps
🦸

sherpa-kenbot

Help Bot for Sherpa Apps

README

# sherpa-kenbot

A small animated cartoon Ken (~160px tall) who floats in the corner of a web app,
answers help questions through *your* AI backend, and speaks his answers aloud in
Ken's cloned ElevenLabs voice with live lip sync. 100% code-drawn SVG — no image
files, no Tailwind dependency, drops into any React 19 app.

He breathes, blinks, glances around, occasionally strolls along the bottom of the
screen, waves hello, leans in to listen, puts his hand to his chin while thinking,
and his mouth moves to the actual loudness of his voice.

## Install

```bash
npm install github:klill6506/sherpa-kenbot
```

Peer dependencies: `react` and `react-dom` (v19). Everything else comes along
automatically. The package builds itself on install (the `prepare` script), so
the first install takes a few extra seconds.

## Quick start (Vite / React / Tailwind host)

```tsx
// App.tsx (or any layout component that's always mounted)
import { KenBot } from 'sherpa-kenbot';
import 'sherpa-kenbot/styles.css';

export function App() {
  return (
    <>
      {/* ...your app... */}
      <KenBot
        askEndpoint="/api/help/"        // your AI backend (see Backend below)
        ttsEndpoint="/api/kenbot/tts/"  // your voice proxy (see Voice below)
      />
    </>
  );
}
```

That's the whole integration. The CSS is plain, prefixed `kb-`, and coexists
fine with Tailwind v4 — no config anywhere.

## Props

| Prop | Default | What it does |
| --- | --- | --- |
| `onAsk` | — | Backend option A: `(message, history) => Promise<string> \| AsyncIterable<string>` |
| `askEndpoint` | — | Backend option B: URL; receives `POST {message, history}`, may stream text |
| `ttsEndpoint` | — | Voice proxy URL; receives `POST {text}` per sentence, returns audio. Omit = text-only |
| `ttsHeaders` | — | Extra headers for TTS requests (e.g. `{'X-CSRFToken': ...}` for Django session auth) |
| `name` | `"Ken"` | Chat header name |
| `greeting` | a friendly hello | First message in the bubble |
| `position` | 

…(truncated for upload size)

STATUS

No STATUS.

DECISIONS

No DECISIONS.

MEMORY

No MEMORY.

CLAUDE.md

# sherpa-kenbot

A reusable React component package: a small (~160px tall) animated cartoon helper —
"KenBot" — who floats in the corner of Ken's web apps, answers help questions through a
pluggable AI backend, and speaks answers aloud in Ken's cloned ElevenLabs voice with lip
sync. Installed across multiple host apps via `npm install github:<account>/sherpa-kenbot`.

## Who Ken is

Ken is a CPA learning to code. Keep code readable; comment the non-obvious parts
(state machine, audio analyser, timers) generously. Explain decisions in plain English.

## Stack & conventions

- Vite **library mode**, React 19, TypeScript **strict** — `any` is banned.
- Peer deps: `react`, `react-dom` only. `motion` (Framer Motion) is a regular dependency.
- Styling: plain CSS bundled with the package, every class prefixed `kb-`.
  **No Tailwind dependency** — must drop into any host app.
- Character is 100% code-drawn SVG in layered groups (body, head, hair, glasses,
  eyes, eyebrows, mouth with 0–1 openness, left/right arms). No image files.
- npm workspaces: root = the library, `demo/` = the playground app.
  `npm run dev` at the root launches the demo. The demo aliases `sherpa-kenbot` → `../src`
  so library edits hot-reload without a build step.
- Respect `prefers-reduced-motion`: keep blinks, drop bounce/gestures.
- Unit tests (vitest): state machine + TTS sentence queue, once those exist.

## Architecture (current)

- `src/state/stateMachine.ts` — PURE state machine (no React, no timers):
  8 states, `reduce(current, event)`. Timed states (greet/celebrate/point-*)
  auto-return to idle; stale timers are ignored. Unit-tested.
- `src/hooks/useKenBotState.ts` — React plumbing around the machine: holds the
  live state, schedules/cancels timed-state timers. Also `useFakeTalk` (random
  cartoon lip-flap for the talking state until Phase 4's real audio).
- `src/character/Character.tsx` — pure presentational SVG. Takes `appearance`
  (colors/hair/glasses) + `pose` (mouthOpen, eyesOpen, 

…(truncated for upload size)

Diary mentions

No recent diary mentions.