# Tiny Workshop Development Roadmap

**Last Updated:** 2026-01-11
**Status:** Active Development

This document outlines the development phases for Tiny Workshop, providing clarity on what's implemented, what's next, and future plans.

---

## Current Phase: MVP ✅ (COMPLETE)

**Goal:** Basic chat interface working end-to-end with Claude Agent SDK

### Completed ✅

| Feature | Status | Notes |
|---------|--------|-------|
| IPC Protocol | ✅ Done | JSON-RPC over stdin/stdout |
| Backend Process Management | ✅ Done | Spawning, lifecycle, error handling |
| Chat UI (Fyrox-UI) | ✅ Done | Streaming messages, input field |
| OAuth Authentication | ✅ Done | PKCE flow, keychain integration |
| Credential Manager | ✅ Done | Cross-platform keychain (Windows, macOS, Linux) |
| Debug Server | ✅ Done | HTTP API for automated testing |
| Animation State Machine | ✅ Done | Color-coded placeholder cube |
| Cross-Platform Backend Path | ✅ Done | Platform detection for backend executable |
| Linux Keychain Fallback | ✅ Done | Config file fallback when Secret Service unavailable |
| Basic Error Recovery | ✅ Done | Auto-restart on backend crash (up to 3 attempts) |
| SDK Integration | ✅ Done | OAuth proxy, multi-turn via InputGenerator pattern |
| Multi-Turn Conversations | ✅ Done | Long-running query with async input generator |

### MVP Definition of Done ✅

- [x] User can authenticate via OAuth
- [x] User can send a message and receive a streaming response
- [x] Application runs on Windows, macOS, and Linux
- [x] Backend crashes don't crash the frontend
- [x] Debug server enables automated testing

**MVP Status: COMPLETE** 🎉

---

## Phase 2: Room System ✅ (COMPLETE)

**Goal:** Agent can interact with the 3D environment

### Completed ✅

| Feature | Status | Notes |
|---------|--------|-------|
| All 5 surfaces | ✅ Done | desk (6), windowside_table (4), mantelpiece (3), bookshelf (8), lectern (2) |
| `create_note` MCP tool | ✅ Done | Via SDK in-process MCP server |
| `remove_note` MCP tool | ✅ Done | Removes notes by title |
| `move_note` MCP tool | ✅ Done | Move notes between surfaces with rollback |
| `examine` tool | ✅ Done | Get details about a specific note |
| `look_around` MCP tool | ✅ Done | Returns room description with note colors |
| `clear_room` tool | ✅ Done | Clears all notes from room |
| Room persistence | ✅ Done | State saves to `room.json` |
| Isometric camera | ✅ Done | 45° isometric view of room |
| Surface placeholder visuals | ✅ Done | Colored meshes for each surface |
| Sticky note rendering | ✅ Done | Colored cubes positioned on surfaces |
| Visual sync | ✅ Done | Room visuals update after actions |
| Image stacks | ✅ Done | Full texture rendering with LRU cache (50 images/50MB) |
| Text on notes | ✅ Done | Title + content preview rendered to 512x512 PNG textures |

### Deferred to Phase 4 (requires 3D assets)

| Feature | Reason |
|---------|--------|
| Real 3D assets | Proper furniture models and note meshes (placeholder cubes for now) |

### Dependencies

- ✅ MVP SDK integration complete
- Design doc: [room-system.md](./design/room-system.md)

---

## Phase 3: Persistence ✅ (COMPLETE)

**Goal:** State survives across sessions and crashes

### Completed ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Room State | ✅ Done | `room.json` with surfaces and interactables |
| Atomic Writes | ✅ Done | Temp file + rename pattern |
| Multi-Instance Safety | ✅ Done | File locking via `fs2` crate |
| Schema Versioning | ✅ Done | Version field with migration support |
| Session Logs | ✅ Done | JSONL append-only with SessionLogger |
| Session Picker UI | ✅ Done | `session_picker.rs` with resume/new options |
| Session Resumption | ✅ Done | Load history, extract SDK session ID, resume via backend |
| Compaction Handling | ✅ Done | Tracks new SDK session ID after compaction |
| Project Metadata | ✅ Done | `project.json` with name, timestamps |
| Session Log Size Limits | ✅ Done | 1000 entries or 10MB limit with `should_rotate()` API |

### Dependencies

- ✅ Room System (Phase 2) for room state
- Design doc: [persistence-system.md](./design/persistence-system.md)

---

## Phase 4: Character & Animation

**Goal:** Replace placeholder cube with animated character

### Planned Features

| Feature | Description |
|---------|-------------|
| Character Model | Low-poly humanoid (~5K triangles) |
| Skeletal Animation | Idle, working, speaking, tool animations |
| Blend Shapes | Facial expressions (jaw, brow, smile, blink) |
| Animation Events | Fyrox animation machine integration |
| Tool-Specific Animations | Different poses for different tool categories |
| Real Room Assets | Proper furniture meshes (desk, bookshelf, etc.) |

### Asset Requirements

- Character mesh (~5K triangles)
- Humanoid skeleton (~50 bones)
- 13 animation clips (see animation-system.md)
- Facial blend shapes

### Dependencies

- Animation state machine (✅ MVP complete with placeholder)
- Design doc: [animation-system.md](./design/animation-system.md)

---

## Phase 5: Polish & UX

**Goal:** Refined user experience

### Completed Features

| Feature | Notes |
|---------|-------|
| Settings Dialog | Graphics (quality preset), Audio (volume/enable), Auth (API key), Advanced tabs. Settings apply at startup and when saved. |

### Planned Features

| Feature | Description |
|---------|-------------|
| Checkpoint Restoration | Double-Esc to restore past state |
| Session Management | Ctrl+N new session, session switching |
| Keyboard Shortcuts | Full shortcut implementation |
| Sound Effects | Audio feedback for actions |
| UI Polish | Transitions, hover states, visual feedback |

### Dependencies

- Core systems stable (Phases 1-4)

---

## Phase 6: Distribution

**Goal:** Ready for public release

### Planned Features

| Feature | Description |
|---------|-------------|
| Windows Installer | MSI or NSIS installer |
| macOS App Bundle | Signed .app bundle |
| Linux Packages | AppImage, .deb, .rpm |
| Auto-Update | In-app update mechanism |
| Crash Reporting | Optional telemetry |

### Dependencies

- All core features complete and stable

---

## Deferred / Future Ideas

Features considered but not currently planned:

| Feature | Reason |
|---------|--------|
| WebAssembly Build | Performance concerns, complexity |
| Mobile (Android/iOS) | Touch UI redesign needed |
| Multiplayer | Out of scope for v1 |
| Custom Character Skins | After core character works |
| Plugin System | After architecture stabilizes |

---

## Known Issues Tracker

Active issues are tracked in [ISSUES.md](./design/ISSUES.md).

**Resolved:**
- Issue #2: ✅ Room state limits implemented
- Issue #3: ✅ Migration snapshot tests implemented
- Issue #4: ✅ Linux keychain fallback implemented
- Issue #7: ✅ Image texture rendering (full-size images, no thumbnails needed)
- Issue #8: ✅ Settings dialog implemented with engine application

**Deferred:**
- Issue #1: Checkpoint restoration (Phase 5)
- Issue #5: Protocol semantic versioning (v2.0)
- Issue #6: Animation event callbacks (Phase 4)

---

## How to Contribute

1. Check this roadmap to understand current priorities
2. Review [ISSUES.md](./design/ISSUES.md) for specific gaps
3. Read relevant design docs in `docs/design/`
4. See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup

---

## Version History

| Date | Changes |
|------|---------|
| 2026-01-11 | Phase 3 fully complete: session log size limits implemented (1000 entries / 10MB) |
| 2026-01-11 | Phase 2 fully complete: image stacks and text rendering done; Issue #7 resolved |
| 2026-01-07 | Moved SDK integration and multi-turn to complete (InputGenerator pattern implemented) |
| 2026-01-06 | Updated Phase 2 & 3 status to reflect implementation; removed duplicate sections |
| 2026-01-05 | Initial roadmap created |