# BMS Forge - Quick Start Guide

## Project Context

### What is this?
A web-based BattleMap Notation Schema (BMS) renderer for DnD/TTRPG maps.

### Current Phase: Planning → Implementation
- **V1 Goal**: Frontend-only BMS renderer with "Paperly" style
- **Deployment**: maps.bouncypixel.com (alpha)
- **Tech Stack**: React + TypeScript + Konva.js + Zod + js-yaml

### Developer Preferences (Lukas)
- **TypeScript**: Strict types but pragmatic about `any`
- **State Management**: Context first, upgrade if needed
- **Error Handling**: Graceful degradation, open to functional libs
- **Testing**: Critical paths first, expand later
- **Components**: Type-based with domain subfolders
- **Styling**: Tailwind hybrid with CSS modules
- **Build**: Vite

## Getting Started (After Break)

1. **Check context**: Read `.opencode-config.json` and `docs/`
2. **Review decisions**: BMS schema format, tech stack, architecture
3. **Continue from**: Last completed task in roadmap

## Key Decisions Made

### Architecture
- **Frontend-only MVP**: No backend needed initially
- **BMS 1.0 Schema**: Defined in `docs/BMS_SCHEMA_SPEC.md`
- **Rendering Engine**: Konva.js with layered rendering
- **Validation**: Zod for runtime schema validation
- **Editor**: Monaco Editor for YAML editing

### Business Model
- **Free Tier**: Paperly style rendering
- **Monetization**: Texture packs + AI subscription
- **Community**: BMS schema as sharing format

### Deployment
- **Alpha**: maps.bouncypixel.com
- **Version Control**: Private Forgejo at git.bouncypixel.com
- **Future**: Potential custom domain (bms-forge.com)

## Next Immediate Actions

Based on current roadmap (`docs/IMPLEMENTATION_ROADMAP.md`):

### Week 1, Days 1-2: Project Setup
```bash
npm create vite@latest bms-forge -- --template react-ts
cd bms-forge
npm install konva react-konva js-yaml zod @monaco-editor/react
npm install tailwindcss postcss autoprefixer
npm install -D @types/js-yaml @types/node
```

### Project Structure to Create
```
src/
├── types/          # BMS TypeScript interfaces
├── schema/         # Zod validation schemas  
├── parser/         # YAML parsing utilities
├── renderer/       # Konva.js rendering engine
├── components/     # Type-based with domains
│   ├── layout/     # Header, Sidebar, etc.
│   ├── canvas/     # Map rendering components
│   ├── editor/     # YAML editor components
│   └── shared/     # Common UI components
├── hooks/          # Custom React hooks
├── utils/          # Helper functions
└── App.tsx
```

## When You Return

1. **Check status**: What was last completed?
2. **Read decisions**: Review config and docs
3. **Pick up**: Continue from next logical step
4. **Ask**: "What should we work on next?"

## Common Commands
```bash
# Development
npm run dev

# Build
npm run build

# Type checking
npm run type-check

# Linting
npm run lint
```

## Questions to Consider When Continuing

1. **Parsing complete?** Can we parse BMS YAML yet?
2. **Rendering working?** Are rooms showing on canvas?
3. **UI usable?** Editor + preview layout functional?
4. **Testing needed?** Critical paths covered?

---
*Last Updated: 2026-03-19*
*Project: BMS Forge - BattleMap Generator*