Skip to content

CLAUDE.md

Latest commit

 

History

History
96 lines (67 loc) · 3.56 KB

CLAUDE.md

File metadata and controls

96 lines (67 loc) · 3.56 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Big Banana Emoji Maker 是一个基于浏览器的 GIF 动画处理工具，所有处理均在客户端完成。项目使用 React 19 + TypeScript + Vite 构建，采用 Zustand 进行状态管理。

Development Commands

# Install dependencies (uses pnpm)
pnpm install

# Start development server (Vite dev server with HMR)
pnpm dev

# Build for production (TypeScript compilation + Vite build)
pnpm build

# Lint code (ESLint)
pnpm lint

# Preview production build
pnpm preview

Architecture

Core Features (3 独立功能模块)

  1. GIF Extractor (src/components/features/GifExtractor.tsx)

    • 使用 gifuct-js 解析 GIF 文件并提取帧
    • 核心逻辑: src/utils/gifParser.ts - 处理 GIF 解析、帧合成和 disposal methods

  2. Sprite Slicer (src/components/features/SpriteSlicer.tsx)

    • 将精灵图按行列切割为独立帧
    • 核心逻辑: src/utils/spriteSlicer.ts - 网格切割和预览绘制

  3. GIF Composer (src/components/features/GifComposer.tsx)

    • 从图片序列生成 GIF 动画，支持拖拽排序
    • 核心逻辑: src/utils/gifGenerator.ts - 使用 gif.js 生成 GIF
    • 使用 @dnd-kit 实现帧排序

State Management

Zustand Store (src/store/useAppStore.ts) - 单一全局状态树，包含：

  • GIF Extractor state: extractedFrames
  • Sprite Slicer state: spriteImage, spriteSlices, spriteRows, spriteCols
  • GIF Composer state: composerImages, gifSettings, generatedGif
  • Global state: isProcessing, logs

所有功能模块通过 Zustand store 共享状态，无需 props drilling。

Key Technical Details

GIF Processing Pipeline:

  • 解析: gifuct-js 解压 GIF 帧 → 处理 disposal types (0/1/2/3) → 合成完整帧
  • 生成: Canvas 绘制 → gif.js Web Worker 编码 → Blob 输出
  • Worker script 位于 public/gif.worker.js (必须存在)

Canvas Operations:

  • 所有图像处理使用 Canvas API (ImageData, drawImage, getImageData)
  • 精灵图切割: 计算 cellWidth/cellHeight → 逐格绘制到临时 canvas → 导出 dataURL
  • GIF 帧合成: 处理 aspect ratio → 居中绘制 → 添加到 gif.js encoder

File Downloads:

  • 单文件: src/utils/download.ts - 创建临时 <a> 元素触发下载
  • 批量文件: 使用 JSZip 打包为 ZIP

UI Components

  • 基础组件 (src/components/ui/): Button, Card, NumberInput, UploadButton
  • 布局组件: Navbar (src/ui/Navbar.tsx), Footer (src/components/Footer.tsx)
  • 样式: Tailwind CSS 4 + DaisyUI (配置在 tailwind.config.js)

Build Configuration

  • Vite (vite.config.ts):
    • React plugin with React Compiler (babel-plugin-react-compiler)
    • Tailwind CSS Vite plugin
  • TypeScript: 项目引用配置 (tsconfig.json → tsconfig.app.json + tsconfig.node.json)

Important Notes

  • Public Assets: public/gif.worker.js 是 gif.js 的 Web Worker，必须在 public 目录中
  • Browser-Only: 所有处理在浏览器完成，无后端依赖
  • Performance: GIF 生成使用 2 个 Web Workers 并行处理
  • Error Handling: 使用 store 的 addLog 方法记录操作日志（最多保留 50 条）

Code Patterns

  • 异步处理: 所有文件读取和图像处理使用 async/await
  • Progress Callbacks: 长时间操作（解析、切片、生成）支持 onProgress 回调
  • Type Safety: 所有类型定义在 src/types/index.ts
  • ID Generation: 使用 crypto.randomUUID() 生成唯一 ID