Update README.md

2025-08-31 15:14:08 +07:00
parent 9ba8f37fe1
commit 5de7d56c45
1 changed files with 223 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,223 @@
-# NanoBananaEditor
-The most advanced Nano Banana image generator and editor application frameworks. Your starting point for a beautiful AI image generation, revisions, featuring easy use of reference images, editing with masked direction and more. Powered by Gemini 2.5 Flash images API.
+# 🍌 Nano Banana Image Editor
+
+> **🚀 Get Your Free Copy!** Join the [Vibe Coding is Life Skool Community](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41) and get a **1-click Bolt.new installation clone** of this app, plus access to live build sessions, exclusive project downloads, AI prompts, masterclasses, and the best vibe coding community on the web!
+
+---
+
+**Professional AI Image Generation & Conversational Editing Platform**
+
+A production-ready React + TypeScript application for delightful image generation and conversational, region-aware revisions using Google's Gemini 2.5 Flash Image model. Built with modern web technologies and designed for both creators and developers.
+
+![Nano Banana Image Editor](https://images.pexels.com/photos/1037992/pexels-photo-1037992.jpeg?auto=compress&cs=tinysrgb&w=1200&h=400&fit=crop)
+
+## ✨ Key Features
+
+### 🎨 **AI-Powered Creation**
+- **Text-to-Image Generation** - Create stunning images from descriptive prompts
+- **Live Quality Tips** - Real-time feedback to improve your prompts
+- **Reference Image Support** - Use up to 2 reference images to guide generation
+- **Advanced Controls** - Fine-tune creativity levels and use custom seeds
+
+### ✏️ **Intelligent Editing**
+- **Conversational Editing** - Modify images using natural language instructions
+- **Region-Aware Selection** - Paint masks to target specific areas for editing
+- **Style Reference Images** - Upload reference images to guide editing style
+- **Non-Destructive Workflow** - All edits preserve the original image
+
+### 🖼️ **Professional Canvas**
+- **Interactive Canvas** - Zoom, pan, and navigate large images smoothly
+- **Brush Tools** - Variable brush sizes for precise mask painting
+- **Mobile Optimized** - Responsive design that works beautifully on all devices
+- **Keyboard Shortcuts** - Efficient workflow with hotkeys
+
+### 📚 **Project Management**
+- **Generation History** - Track all your creations and edits
+- **Variant Comparison** - Generate and compare multiple versions side-by-side
+- **Full Undo/Redo** - Complete generation tree with branching history
+- **Asset Management** - Organized storage of all generated content
+
+### 🔒 **Enterprise Features**
+- **SynthID Watermarking** - Built-in AI provenance with invisible watermarks
+- **Offline Caching** - IndexedDB storage for offline asset access
+- **Type Safety** - Full TypeScript implementation with strict typing
+- **Performance Optimized** - React Query for efficient state management
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Node.js 18+ 
+- A [Google AI Studio](https://aistudio.google.com/) API key
+
+### Installation
+
+1. **Clone and install dependencies**:
+   ```bash
+   git clone <repository-url>
+   cd nano-banana-image-editor
+   npm install
+   ```
+
+2. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Add your Gemini API key to VITE_GEMINI_API_KEY
+   ```
+
+3. **Start development server**:
+   ```bash
+   npm run dev
+   ```
+
+4. **Open in browser**: Navigate to `http://localhost:5173`
+
+## 🎯 Usage Guide
+
+### Creating Images
+1. Select **Generate** mode
+2. Write a detailed prompt describing your desired image
+3. Optionally upload reference images (max 2)
+4. Adjust creativity settings if needed
+5. Click **Generate** or press `Cmd/Ctrl + Enter`
+
+### Editing Images
+1. Switch to **Edit** mode
+2. Upload an image or use a previously generated one
+3. Optionally paint a mask to target specific areas
+4. Describe your desired changes in natural language
+5. Click **Apply Edit** to see the results
+
+### Advanced Workflows
+- Use **Select** mode to paint precise masks for targeted edits
+- Compare variants in the History panel
+- Download high-quality PNG outputs
+- Use keyboard shortcuts for efficient navigation
+
+## ⌨️ Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd/Ctrl + Enter` | Generate/Apply Edit |
+| `Shift + R` | Re-roll variants |
+| `E` | Switch to Edit mode |
+| `G` | Switch to Generate mode |
+| `M` | Switch to Select mode |
+| `H` | Toggle history panel |
+| `P` | Toggle prompt panel |
+
+## 🏗️ Architecture
+
+### Tech Stack
+- **Frontend**: React 18, TypeScript, Tailwind CSS
+- **State Management**: Zustand for app state, React Query for server state  
+- **Canvas**: Konva.js for interactive image display and mask overlays
+- **AI Integration**: Google Generative AI SDK (Gemini 2.5 Flash Image)
+- **Storage**: IndexedDB for offline asset caching
+- **Build Tool**: Vite for fast development and optimized builds
+
+### Project Structure
+```
+src/
+├── components/          # React components
+│   ├── ui/             # Reusable UI components (Button, Input, etc.)
+│   ├── PromptComposer.tsx  # Prompt input and tool selection
+│   ├── ImageCanvas.tsx     # Interactive canvas with Konva
+│   ├── HistoryPanel.tsx    # Generation history and variants
+│   ├── Header.tsx          # App header and navigation
+│   └── InfoModal.tsx       # About modal with links
+├── services/           # External service integrations
+│   ├── geminiService.ts    # Gemini API client
+│   ├── cacheService.ts     # IndexedDB caching layer
+│   └── imageProcessing.ts  # Image manipulation utilities
+├── store/              # Zustand state management
+│   └── useAppStore.ts      # Global application state
+├── hooks/              # Custom React hooks
+│   ├── useImageGeneration.ts  # Generation and editing logic
+│   └── useKeyboardShortcuts.ts # Keyboard navigation
+├── utils/              # Utility functions
+│   ├── cn.ts              # Class name utility
+│   └── imageUtils.ts      # Image processing helpers
+└── types/              # TypeScript type definitions
+    └── index.ts           # Core type definitions
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+```bash
+VITE_GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+### Model Configuration
+- **Model**: `gemini-2.5-flash-image-preview`
+- **Output Format**: 1024×1024 PNG with SynthID watermarks
+- **Input Formats**: PNG, JPEG, WebP
+- **Temperature Range**: 0-1 (0 = deterministic, 1 = creative)
+
+## 🚀 Deployment
+
+### Development
+```bash
+npm run dev      # Start development server
+npm run build    # Build for production
+npm run preview  # Preview production build
+npm run lint     # Run ESLint
+```
+
+### Production Considerations
+- **API Security**: Implement backend proxy for API calls in production
+- **Rate Limiting**: Add proper rate limiting and usage quotas
+- **Authentication**: Consider user authentication for multi-user deployments
+- **Storage**: Set up cloud storage for generated assets
+- **Monitoring**: Add error tracking and analytics
+
+## 📄 License & Copyright
+
+**Copyright © 2025 [Mark Fulton](https://markfulton.com)**
+
+This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).
+
+### What this means:
+- ✅ **Free to use** for personal and commercial projects
+- ✅ **Modify and distribute** with proper attribution
+- ⚠️ **Share modifications** - Any changes must be shared under the same license
+- ⚠️ **Network use** - If you run this as a web service, you must provide source code
+
+See the [LICENSE](LICENSE) file for full details.
+
+## 🤝 Contributing
+
+We welcome contributions! Please:
+
+1. **Follow the established patterns** - Keep components under 200 lines
+2. **Maintain type safety** - Use TypeScript strictly with proper definitions
+3. **Test thoroughly** - Ensure keyboard navigation and accessibility
+4. **Document changes** - Update README and add inline comments
+5. **Respect the license** - All contributions will be under AGPL-3.0
+
+## 🔗 Links & Resources
+
+- **Creator**: [Mark Fulton](https://markfulton.com)
+- **AI Training Program**: [Reinventing.AI](https://www.reinventing.ai/)
+- **Community**: [Vibe Coding is Life Skool](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41)
+- **Google AI Studio**: [Get your API key](https://aistudio.google.com/)
+- **Gemini API Docs**: [Official Documentation](https://ai.google.dev/gemini-api/docs)
+
+## 🐛 Known Issues & Limitations
+
+- **Client-side API calls** - Currently uses direct API calls (implement backend proxy for production)
+- **Browser compatibility** - Requires modern browsers with Canvas and WebGL support
+- **Rate limits** - Subject to Google AI Studio rate limits
+- **Image size** - Optimized for 1024×1024 outputs (Gemini model limitation)
+
+## 🎯 Roadmap
+
+- [ ] Backend API proxy implementation
+- [ ] User authentication and project sharing
+- [ ] Advanced brush tools and selection methods
+- [ ] Batch processing capabilities
+- [ ] Plugin system for custom filters
+- [ ] Integration with cloud storage providers
+
+---
+
+**Built with ❤️ by the Vibe Coding community** | **Powered by Gemini 2.5 Flash Image** | **Made with Bolt.new**