xiaodao-painter 0.1.8 → 0.1.9

package/README.ZH.md

@@ -0,0 +1,362 @@
+# 小刀画板工具 (Xiaodao Painter)
+
+**中文** | [English](./README.md) | [演示](https://painter.xdz.me)
+
+[![Downloads](https://img.shields.io/npm/d18m/xiaodao-painter)](https://www.npmjs.com/package/xiaodao-painter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/xiaodao-painter)](https://www.npmjs.com/package/xiaodao-painter)
+[![Vue 3](https://img.shields.io/badge/Vue-3.5+-42b883.svg)](https://vuejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0+-3178C6.svg)](https://www.typescriptlang.org/)
+[![Vite](https://img.shields.io/badge/Vite-8.0+-646CFF.svg)](https://vitejs.dev/)
+
+一个自包含、可嵌入的 Vue 3 SVG 画板 / 绘图组件：把功能完整的画布（自由铅笔、基础图形、文本、选择与变换、平移缩放、撤销重做、内部剪贴板、颜色系统、明/暗主题、内置中英文国际化）打包进单个组件，并通过一个 `v-model` 驱动。
+
+![预览](./img/preview.png)
+
+---
+
+## 功能特性
+
+### 绘制与编辑
+
+- **9 种工具**：选择、平移、铅笔、直线、矩形、圆、三角形、五角星、文本（另含独立的缩放工具）。
+- **选择与变换**：单击选择；空白拖动框选；拖动已选图形移动；8 个手柄缩放（Shift = 对称 / 中心扩展）；图层顺序（上移 / 下移）。
+- **平移与缩放**：拖动平移画布；离散缩放档位（10%–1000%）以光标为锚点；触屏支持双指捏合缩放。
+- **撤销 / 重做**：完整的笔画级撤销/重做栈。
+- **内部剪贴板**：剪切、复制、粘贴（粘贴时偏移 +20px）。
+- **颜色系统**：描边（前景）、填充（背景）、文本颜色三个色槽；可对选中图形逐个应用颜色，画布背景支持纯色或透明网格。
+- **文本工具**：单击放置可编辑文本框；双击已有文本进行编辑。
+
+### 交互
+
+- **指针与触屏**：统一的 `useDrawing` 交互层同时处理鼠标与触摸路径，包括双指捏合缩放、拖动绘制/选择。
+- **缩放手柄**：图形 8 个、直线 2 个端点，拖动时实时预览。
+- **修饰键**：`Ctrl` = 锁定 1:1 比例（闭合图形）；`Shift` = 中心扩展 / 直线 45° 吸附。
+- **快捷键**：Delete、Esc、Ctrl/⌘+Z / Ctrl/⌘+Y / Ctrl/⌘+X / Ctrl/⌘+C / Ctrl/� (V。
+- **SVG 渲染**：每一条笔画都是真实的 SVG 元素（`<path>`、`<line>`、`<ellipse>`、`<rect>`、`<polygon>`、`foreignObject`），输出与分辨率无关、易于导出。
+
+### 视觉与主题
+
+- **明 / 暗主题**：由 CSS 变量（`--wb-*`）驱动，切换主题只是换一个 class。
+- **国际化**：内置中文（`zh-CN`）与英文（`en-US`），工具栏文案与缩放指示均走 `t()` 字典。
+- **双向绑定**：通过 `v-model` 读写整份绘图数据。
+
+---
+
+## 安装
+
+```bash
+# npm
+npm install xiaodao-painter
+# pnpm
+pnpm add xiaodao-painter
+# yarn
+yarn add xiaodao-painter
+```
+
+### 对等依赖
+
+- `vue` `^3.0.0`
+
+需要引入一次样式文件：
+
+```ts
+import 'xiaodao-painter/style.css'
+```
+
+---
+
+## 快速开始
+
+```bash
+# 克隆仓库
+git clone https://github.com/xiaodaozhi/xiaodao-painter.git
+cd xiaodao-painter
+
+# 安装依赖
+npm install
+
+# 启动开发服务器（演示页）
+npm run dev
+```
+
+在浏览器打开 `http://localhost:5173` 查看演示应用。
+
+要构建独立演示页，运行 `npm run build:demo` 并打开 `dist-demo/index.html`。
+
+---
+
+## 基础用法
+
+```vue
+<template>
+  <Painter
+    v-model="data"
+    theme="light"
+    locale="zh-CN"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { Painter } from 'xiaodao-painter'
+import type { PainterData } from 'xiaodao-painter'
+import 'xiaodao-painter/style.css'
+
+const data = ref<PainterData>({
+  strokes: [],
+  canvasWidth: 800,
+  canvasHeight: 600,
+})
+
+watch(data, (val) => {
+  console.log('绘图数据变化：', val)
+}, { deep: true })
+</script>
+```
+
+### 指定尺寸与暗色主题
+
+```html
+<Painter
+  v-model="data"
+  theme="dark"
+  locale="en-US"
+  :width="1200"
+  :height="800"
+/>
+```
+
+### 自定义画布背景
+
+```html
+<Painter
+  v-model="data"
+  :modelValue="{
+    strokes: [],
+    canvasWidth: 800,
+    canvasHeight: 600,
+    canvasBackgroundColor: '#f5f5f5',
+  }"
+/>
+```
+
+---
+
+## Props（属性）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|---------|------|
+| `modelValue` (v-model) | `PainterData` | `{ strokes: [], canvasWidth: 800, canvasHeight: 600 }` | 双向绑定的绘图数据，支持 `canvasBackgroundColor`。 |
+| `theme` | `'light' \| 'dark'` | `'light'` | 界面主题。 |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 界面语言，传入其他值回退到 `zh-CN`。 |
+| `width` | `string \| number` | `'100%'` | 组件宽度（CSS 值或 px 数值）。 |
+| `height` | `string \| number` | `'100%'` | 组件高度（CSS 值或 px 数值）。 |
+
+---
+
+## 数据模型
+
+整份绘图由一个可序列化的 `PainterData` 对象描述，便于持久化、撤销重做与协作。
+
+```ts
+interface PainterData {
+  strokes: Stroke[]
+  canvasWidth: number
+  canvasHeight: number
+  canvasBackgroundColor?: string   // 任意 CSS 颜色或 'transparent'
+}
+
+type ToolType =
+  | 'select' | 'pan' | 'zoom'
+  | 'pencil' | 'line' | 'circle' | 'rect' | 'triangle' | 'star'
+  | 'text'
+
+interface Point { x: number; y: number }
+
+interface Stroke {
+  id: string                       // crypto.randomUUID()
+  type: ToolType
+  x: number                        // 包围盒左上角（提交时归一化）
+  y: number
+  width: number                    // 包围盒宽（绘制中可能为负）
+  height: number
+  points: Point[]                  // 铅笔路径点；非铅笔图形为空
+  strokeColor: string
+  fillColor: string                // 铅笔与直线为 'transparent' / 'none'
+  strokeWidth: number
+  // 仅文本图形
+  text?: string
+  fontSize?: number
+  textAlign?: 'left' | 'center' | 'right'
+  textColor?: string
+  textAutoWidth?: boolean
+}
+```
+
+坐标统一保存在**画布（SVG 用户）坐标系**中，与缩放和平移无关。组件在提交时会把负宽高的图形归一化，保证存储的包围盒始终为正。
+
+### 类型导出
+
+```ts
+import type {
+  PainterData,        // 主数据接口
+  Stroke,             // 单条笔画 / 图形 / 文本
+  Point,              // { x: number; y: number }
+  ToolType,           // 所有工具标识的联合类型
+  CanvasConfig,       // 画布尺寸 / 背景配置
+} from 'xiaodao-painter'
+
+import {
+  DEFAULT_CANVAS_WIDTH,
+  DEFAULT_CANVAS_HEIGHT,
+  STROKE_WIDTH,
+  DEFAULT_FONT_SIZE,
+  HIT_THRESHOLD,
+} from 'xiaodao-painter'
+```
+
+---
+
+## 架构
+
+```src/
+├── index.ts                         # 公开入口：导出 Painter 与类型/常量
+├── App.vue                          # 演示根组件（设置页面标题、挂载组件）
+├── style.css                        # 全局主题 CSS 变量（明/暗）
+└── components/painter/
+    ├── Painter.vue                  # 公开组件：props、v-model 同步、主题/语言注入
+    ├── Whiteboard.vue               # SVG 画布、指针/触摸处理、缩放 UI、文本编辑
+    ├── Toolbar.vue                  # 工具按钮、颜色指示、画布尺寸弹窗
+    ├── ColorPalette.vue             # 前景/填充/文本色槽的颜色选择器
+    ├── SelectionOverlay.vue         # 包围框 + 8 个缩放手柄（直线仅 2 个）
+    ├── StrokeRenderer.vue           # 把单个 Stroke 渲染为 SVG 元素
+    ├── composables/
+    │   ├── useDrawing.ts            # 交互引擎（绘制/选择/移动/缩放/平移/文本）
+    │   └── useI18n.ts               # locale、theme、根元素的 provide/inject
+    ├── stores/
+    │   ├── canvas.ts                # 中心仓库：笔画、颜色、平移缩放、撤销、剪贴板
+    │   └── tools.ts                 # 当前工具状态
+    ├── utils/
+    │   ├── geometry.ts              # 命中测试、星/三角形顶点、包围盒
+    │   ├── svg.ts                   # Stroke → SVG 元素转换
+    │   └── i18n.ts                  # zh-CN / en-US 字典 + t()
+    └── types/index.ts               # TypeScript 类型与默认常量
+```
+
+### 设计原则
+
+- **自包含**：单个 Vue 3 组件，除 Vue 外零运行时依赖，无需全局注册，无需 CSS 框架。
+- **状态可序列化**：整份绘图是单个普通对象（`PainterData`），便于保存、加载与同步。
+- **基于 SVG 渲染**：每条笔画都是真实 SVG 节点（`<path>`、`<line>`、`<ellipse>`、`<rect>`、`<polygon>`、`foreignObject`），输出与分辨率无关、易主题化、易导出。
+- **可预测的双向绑定**：父组件拥有数据，组件回显并在变更时通过 `v-model` 上报；store 内的 `syncing` 标志与组件内的 `suppressing` 标志共同避免回环。
+- **轻量交互**：手动处理指针与触摸事件并显式计算坐标变换（不使用 `getScreenCTM`），规避 CSS transform 下 iOS Safari 的不一致行为。
+- **纯函数工具**：命中测试、SVG 转换、i18n 都放在 `utils/` 中作为无框架依赖的纯函数，易于复用与单测。
+- **组合式 API**：业务逻辑抽离到 `composables/`（`useDrawing`、`useI18n`）与轻量 store 层（`canvas.ts`、`tools.ts`），保持单一职责。
+
+> **单实例说明**：`canvas.ts` 与 `tools.ts` 是模块级响应式单例，同一页面多个 `<Painter>` 会共享状态。若要支持多实例，应将 store 改为基于 `provide`/`inject` 的组件级 store。
+
+---
+
+## 快捷键
+
+| 按键 | 动作 |
+|------|------|
+| `Delete` / `Backspace` | 删除选中图形 |
+| `Escape` | 取消选择 / 取消文本编辑 |
+| `Ctrl/⌘ + Z` | 撤销 |
+| `Ctrl/⌘ + Y` 或 `Ctrl/⌘ + Shift + Z` | 重做 |
+| `Ctrl/⌘ + X` | 剪切 |
+| `Ctrl/⌘ + C` | 复制 |
+| `Ctrl/⌘ + V` | 粘贴（偏移 +20px） |
+
+绘制或缩放过程中，`Ctrl` 锁定 1:1，`Shift` 对闭合图形为中心扩展、对直线为 45° 吸附。
+
+---
+
+## 主题与国际化
+
+### 内置主题
+
+通过 `theme` 属性提供两套主题，颜色由 `style.css` 中的 CSS 变量（`--wb-*`）驱动，自动适配明/暗。切换主题时若当前前景色为默认值，会自动在 `#000000` 与 `#ffffff` 之间翻转。
+
+可在任意外层元素上覆盖 CSS 变量实现深度定制：
+
+```html
+<div style="--wb-bg: #1a1a2e; --wb-text: #e0e0e0;">
+  <Painter v-model="data" theme="dark" />
+</div>
+```
+
+### 国际化
+
+内置 `zh-CN` 与 `en-US` 文案。通过 `locale` 切换，未知取值回退到 `zh-CN`。字典位于 `src/components/painter/utils/i18n.ts`，可方便扩展更多语言。
+
+---
+
+## 开发
+
+```bash
+npm run dev        # 启动 Vite 开发服务器（演示页）
+npm run build      # 类型检查（vue-tsc）并构建库产物
+npm run build:demo # 构建独立演示页到 ./dist-demo
+npm run preview    # 预览库的生产构建
+npm run lint:check # 运行 ESLint
+npm run typecheck  # 仅类型检查
+```
+
+## 构建
+
+库构建通过 `vite.config.ts`（lib 模式）。`npm run build` 产出：
+
+| 文件 | 说明 |
+|------|------|
+| `dist/xiaodao-painter.es.js` | ES 模块（供打包工具使用） |
+| `dist/xiaodao-painter.umd.js` | UMD 包（供直接 `<script>` 引入） |
+| `dist/xiaodao-painter.css` | 提取的样式表 |
+| `dist/types/` | TypeScript 类型声明 |
+
+`npm run build:demo` 通过 `vite.demo.config.ts` 构建独立演示站点到 `dist-demo/`（按 `dist` 同等规则 git 忽略）。
+
+---
+
+## 路线图
+
+### 近期
+
+- [x] 铅笔、图形、文本绘制与选择变换
+- [x] 平移缩放、撤销重做、内部剪贴板
+- [x] 颜色系统、明/暗主题、国际化
+- [ ] 导出 PNG / SVG / JSON
+- [ ] 图形级对齐吸附与参考线
+
+### 中期
+
+- [ ] 多页面 / 多图层支持
+- [ ] 图片嵌入
+- [ ] 云端保存 / 加载集成
+
+### 长期
+
+- [ ] 协同编辑
+- [ ] 自定义图形渲染插件系统
+
+---
+
+## 技术栈
+
+| 层 | 技术 | 版本 |
+|----|------|------|
+| 框架 | Vue 3（Composition API + `<script setup>`） | ^3.5 |
+| 构建 | Vite | ^8.0 |
+| 语言 | TypeScript（strict） | ~6.0 |
+| 渲染 | SVG 2D（DOM） | - |
+| 类型检查 | vue-tsc | ^3.3 |
+| 包管理器 | npm / pnpm | - |
+| CSS | Scoped CSS + CSS 自定义属性 | - |
+
+---
+
+## 许可证
+
+本项目基于 MIT 许可证发布，详见 [LICENSE](LICENSE) 文件。

package/README.md

@@ -1,49 +1,107 @@
-# xiaodao-painter
+# Xiaodao Painter
 
-A self-contained, embeddable SVG whiteboard component for Vue 3. Built with TypeScript and Vite. Zero extra dependencies beyond Vue 3.
+[中文](./README.ZH.md) | **English** | [Demo](https://painter.xdz.me)
 
-Supports drawing tools, selection, resize, pan/zoom, undo/redo, clipboard, layer ordering, color palettes, i18n, and light/dark themes — all with two-way data binding via `v-model`.
+[![Downloads](https://img.shields.io/npm/d18m/xiaodao-painter)](https://www.npmjs.com/package/xiaodao-painter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/xiaodao-painter)](https://www.npmjs.com/package/xiaodao-painter)
+[![Vue 3](https://img.shields.io/badge/Vue-3.5+-42b883.svg)](https://vuejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0+-3178C6.svg)](https://www.typescriptlang.org/)
+[![Vite](https://img.shields.io/badge/Vite-8.0+-646CFF.svg)](https://vitejs.dev/)
+
+A self-contained, embeddable **SVG drawing component** for Vue 3: a full-featured drawing surface (freehand pencil, shape primitives, text, selection & transform, pan & zoom, undo/redo, an internal clipboard, a color system, light/dark themes, and built-in i18n) packed into a single component, driven by one `v-model`.
 
 ![Preview](./img/preview.png)
 
+---
+
 ## Features
 
-- **9 tools** — Select, Pan, Zoom, Pencil, Line, Circle, Rectangle, Triangle, Star
-- **Selection & manipulation** — click to select, box-select, drag-move, 8-handle resize (Shift = symmetric), layer reorder (bring to front / send to back)
-- **Pan & zoom** — grab-drag panning, discrete zoom steps (10% – 1000%) anchored at cursor position
-- **Undo / redo** — full stroke-level undo/redo stacks
-- **Internal clipboard** — cut, copy, paste (within the whiteboard, offset +20 px)
-- **Color system** — stroke (foreground) and fill (background) color slots, per-stroke color application to selections, canvas background color with transparent grid support
-- **Themes** — light and dark, with auto-switching foreground color on theme change
-- **Internationalization** — Chinese (zh-CN) and English (en-US) built in
-- **Keyboard shortcuts** — Delete, Escape, Ctrl+Z / Ctrl+Y / Ctrl+X / Ctrl+C / Ctrl+V
-- **Modifier keys** — Ctrl = constrain 1:1 ratio, Shift = center-out expansion / 45° line snap
-- **Two-way binding** — parent reads/writes full drawing data via `v-model`
+### Drawing & Editing
 
-## Installation
+- **9 tools**: Select, Pan, Pencil, Line, Rectangle, Circle, Triangle, Star, Text (plus a dedicated Zoom tool).
+- **Selection & transform**: Click to select, box-select on empty space, drag to move, 8-handle resize (Shift = center-out / symmetric), layer reorder (bring to front / send to back).
+- **Pan & zoom**: Grab-drag panning, discrete zoom steps (10%–1000%) anchored at the cursor; pinch zoom on touch devices.
+- **Undo / redo**: Full stroke-level undo/redo stacks.
+- **Internal clipboard**: Cut, copy, paste within the canvas (paste offset +20 px).
+- **Color system**: Stroke (foreground), fill (background), and text-color slots; per-selection color application and canvas background (solid or transparent with grid).
+- **Text tool**: Click to place an editable text box; double-click existing text to edit.
+
+### Interaction
+
+- **Pointer & touch**: A single interaction layer (`useDrawing`) unifies mouse and touch paths, including pinch-to-zoom and drag-to-draw/select.
+- **Resize handles**: 8 handles for shapes, 2 endpoints for lines; live preview while dragging.
+- **Modifier keys**: `Ctrl` = constrain 1:1 ratio (shapes), `Shift` = center-out expansion / 45° line snap.
+- **Keyboard shortcuts**: Delete, Escape, Ctrl/⌘+Z / Ctrl/⌘+Y / Ctrl/⌘+X / Ctrl/⌘+C / Ctrl/⌘+V.
+- **SVG rendering**: Every stroke is a real SVG element (`<path>`, `<line>`, `<ellipse>`, `<rect>`, `<polygon>`, `foreignObject`), so the output is resolution-independent and easy to export.
+
+### Visual & Theming
 
-Install the package from npm:
+- **Light / Dark themes**: Full color palette driven by CSS custom properties (`--wb-*`), switching swaps a single class.
+- **Internationalization**: Chinese (`zh-CN`) and English (`en-US`) built in; toolbar labels and zoom indicator route through an `t()` dictionary.
+- **Two-way binding**: Read and write the entire drawing via `v-model`.
+
+---
+
+## Installation
 
 ```bash
+# npm
 npm install xiaodao-painter
+# pnpm
+pnpm add xiaodao-painter
+# yarn
+yarn add xiaodao-painter
 ```
 
-Or with pnpm / yarn:
+### Peer Dependencies
+
+- `vue` `^3.0.0`
+
+Import the stylesheet once:
+
+```ts
+import 'xiaodao-painter/style.css'
+```
+
+---
+
+## Quick Start
 
 ```bash
-pnpm add xiaodao-painter
-yarn add xiaodao-painter
+# Clone the repository
+git clone https://github.com/xiaodaozhi/xiaodao-painter.git
+cd xiaodao-painter
+
+# Install dependencies
+npm install
+
+# Start the dev server (demo page)
+npm run dev
 ```
 
-## Usage
+Navigate to `http://localhost:5173` to see the demo application.
+
+To build a standalone demo page, run `npm run build:demo` and open `dist-demo/index.html`.
+
+---
 
-Just import and use the `Painter` component. No additional plugins or global setup required — only Vue 3 is needed:
+## Basic Usage
 
 ```vue
+<template>
+  <Painter
+    v-model="data"
+    theme="light"
+    locale="zh-CN"
+  />
+</template>
+
 <script setup lang="ts">
 import { ref, watch } from 'vue'
 import { Painter } from 'xiaodao-painter'
 import type { PainterData } from 'xiaodao-painter'
+import 'xiaodao-painter/style.css'
 
 const data = ref<PainterData>({
   strokes: [],
@@ -52,32 +110,24 @@ const data = ref<PainterData>({
 })
 
 watch(data, (val) => {
-  console.log('Drawing data changed:', val)
+  console.log('Drawing changed:', val)
 }, { deep: true })
 </script>
-
-<template>
-  <Painter
-    v-model="data"
-    theme="light"
-    locale="zh-CN"
-  />
-</template>
 ```
 
-With explicit dimensions and dark theme:
+### With explicit dimensions and dark theme
 
 ```html
 <Painter
   v-model="data"
   theme="dark"
   locale="en-US"
-  width="1200"
-  height="800"
+  :width="1200"
+  :height="800"
 />
 ```
 
-With a custom canvas background color:
+### With a custom canvas background
 
 ```html
 <Painter
@@ -91,44 +141,51 @@ With a custom canvas background color:
 />
 ```
 
+---
+
 ## Props
 
 | Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `modelValue` | `PainterData` | `{ strokes: [], canvasWidth: 800, canvasHeight: 600 }` | Two-way bound drawing data (supports `canvasBackgroundColor`) |
-| `theme` | `'light' \| 'dark'` | `'light'` | UI theme |
-| `locale` | `string` | `'zh-CN'` | UI language (`'zh-CN'` or `'en-US'`) |
-| `width` | `string \| number` | `'100%'` | Component width (CSS value or px number) |
-| `height` | `string \| number` | `'100%'` | Component height (CSS value or px number) |
+|------|------|---------|-------------|
+| `modelValue` (v-model) | `PainterData` | `{ strokes: [], canvasWidth: 800, canvasHeight: 600 }` | Two-way bound drawing data. Supports `canvasBackgroundColor`. |
+| `theme` | `'light' \| 'dark'` | `'light'` | UI theme. |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | UI language. Any other value falls back to `zh-CN`. |
+| `width` | `string \| number` | `'100%'` | Component width (CSS value or px number). |
+| `height` | `string \| number` | `'100%'` | Component height (CSS value or px number). |
+
+---
 
 ## Data Model
 
+The whole drawing is described by a single serializable `PainterData` object, which makes persistence, undo/redo, and collaboration straightforward.
+
 ```ts
 interface PainterData {
   strokes: Stroke[]
   canvasWidth: number
   canvasHeight: number
-  canvasBackgroundColor?: string
+  canvasBackgroundColor?: string   // any CSS color or 'transparent'
 }
 
-type ToolType = 'select' | 'pencil' | 'line' | 'circle' | 'rect' | 'triangle' | 'star' | 'text' | 'pan' | 'zoom'
+type ToolType =
+  | 'select' | 'pan' | 'zoom'
+  | 'pencil' | 'line' | 'circle' | 'rect' | 'triangle' | 'star'
+  | 'text'
 
-interface Point {
-  x: number
-  y: number
-}
+interface Point { x: number; y: number }
 
 interface Stroke {
-  id: string
+  id: string                       // crypto.randomUUID()
   type: ToolType
-  x: number
+  x: number                        // bounding-box top-left (normalized on commit)
   y: number
-  width: number
+  width: number                    // bounding-box width (may be negative while drawing)
   height: number
-  points: Point[]
+  points: Point[]                  // pencil path points; empty for non-pencil
   strokeColor: string
-  fillColor: string
+  fillColor: string                // 'transparent' / 'none' for pencil & line
   strokeWidth: number
+  // text-only fields
   text?: string
   fontSize?: number
   textAlign?: 'left' | 'center' | 'right'
@@ -137,52 +194,169 @@ interface Stroke {
 }
 ```
 
+Coordinates are stored in **canvas (SVG user) coordinate space**, independent of zoom and pan. The component normalizes negative-width/height shapes on commit so the stored bounding box is always positive.
+
+### Type Exports
+
+```ts
+import type {
+  PainterData,        // main data interface
+  Stroke,             // a single shape / text / pencil entry
+  Point,              // { x: number; y: number }
+  ToolType,           // union of all tool identifiers
+  CanvasConfig,       // canvas size / background config
+} from 'xiaodao-painter'
+
+import {
+  DEFAULT_CANVAS_WIDTH,
+  DEFAULT_CANVAS_HEIGHT,
+  STROKE_WIDTH,
+  DEFAULT_FONT_SIZE,
+  HIT_THRESHOLD,
+} from 'xiaodao-painter'
+```
+
+---
+
+## Architecture
+
+```src/
+├── index.ts                         # Public entry: exports Painter + types/constants
+├── App.vue                          # Demo root (sets page title, mounts the component)
+├── style.css                        # Global theme CSS variables (light/dark)
+└── components/painter/
+    ├── Painter.vue                  # Public component: props, v-model sync, theme/locale provide
+    ├── Whiteboard.vue               # SVG canvas, pointer/touch handling, zoom UI, text editing
+    ├── Toolbar.vue                  # Tool buttons, color indicators, canvas-size popover
+    ├── ColorPalette.vue             # Color picker for foreground/fill/text slots
+    ├── SelectionOverlay.vue         # Bounding box + 8 resize handles (line gets 2 handles)
+    ├── StrokeRenderer.vue           # Renders one Stroke as an SVG element
+    ├── composables/
+    │   ├── useDrawing.ts            # Interaction engine (draw/select/move/resize/pan/zoom/text)
+    │   └── useI18n.ts               # provide/inject for locale, theme, root element
+    ├── stores/
+    │   ├── canvas.ts                # Central store: strokes, colors, pan/zoom, undo, clipboard
+    │   └── tools.ts                 # Active tool state
+    ├── utils/
+    │   ├── geometry.ts              # Hit testing, star/triangle vertices, bounding box
+    │   ├── svg.ts                   # Stroke → SVG element conversion
+    │   └── i18n.ts                  # zh-CN / en-US dictionaries + t()
+    └── types/index.ts               # TypeScript types and default constants
+```
+
+### Design Principles
+
+- **Self-contained**: A single Vue 3 component with zero runtime dependencies beyond Vue; no global registration, no CSS framework.
+- **Serializable state**: The whole drawing is one plain `PainterData` object, so it can be saved, loaded, and synced trivially.
+- **SVG-based rendering**: Every stroke is a real SVG node (`<path>`, `<line>`, `<ellipse>`, `<rect>`, `<polygon>`, `foreignObject`). Output is resolution-independent, easily themeable, and export-friendly.
+- **Predictable two-way binding**: The parent owns the data; the component reflects it and emits changes back through `v-model`. A `syncing` flag in the store plus a `suppressing` flag in the component prevents feedback loops.
+- **Framework-light interaction**: Pointer + touch are handled manually with an explicit coordinate transform (not `getScreenCTM`), avoiding unreliable behavior under CSS transforms on iOS Safari.
+- **Pure helpers**: Hit-testing, SVG conversion, and i18n live in `utils/` as framework-free functions, easy to reuse or unit-test.
+- **Composition API**: Business logic is extracted into `composables/` (`useDrawing`, `useI18n`) and a small store layer (`canvas.ts`, `tools.ts`), keeping single-responsibility modules.
+
+> **Single-instance note:** `canvas.ts` and `tools.ts` are module-level reactive singletons. Multiple `<Painter>` components on one page currently share state. To support multiple instances, promote the stores to a `provide`/`inject` scoped store per component.
+
+---
+
 ## Keyboard Shortcuts
 
 | Key | Action |
-| --- | --- |
+|-----|--------|
 | `Delete` / `Backspace` | Delete selected strokes |
-| `Escape` | Clear selection |
-| `Ctrl + Z` | Undo |
-| `Ctrl + Y` / `Ctrl + Shift + Z` | Redo |
-| `Ctrl + X` | Cut |
-| `Ctrl + C` | Copy |
-| `Ctrl + V` | Paste (offset +20 px) |
+| `Escape` | Clear selection / cancel text edit |
+| `Ctrl/⌘ + Z` | Undo |
+| `Ctrl/⌘ + Y` or `Ctrl/⌘ + Shift + Z` | Redo |
+| `Ctrl/⌘ + X` | Cut |
+| `Ctrl/⌘ + C` | Copy |
+| `Ctrl/⌘ + V` | Paste (offset +20 px) |
 
-## Project Structure
+While drawing or resizing, `Ctrl` constrains to 1:1, `Shift` gives center-out expansion (for closed shapes) or 45° line snapping (for lines).
 
+---
+
+## Theming & Internationalization
+
+### Built-in Themes
+
+The component ships two themes via the `theme` prop. Colors are driven by CSS custom properties defined in `style.css` (`--wb-*`), so the component adapts to light/dark automatically. Switching theme also flips the default foreground color (`#000000` ⇄ `#ffffff`) when the current color is the theme default.
+
+Override CSS variables on any wrapper element for full customization:
+
+```html
+<div style="--wb-bg: #1a1a2e; --wb-text: #e0e0e0;">
+  <Painter v-model="data" theme="dark" />
+</div>
 ```
-src/
-  components/painter/
-    Painter.vue            # Public entry (props, v-model, theme sync)
-    Whiteboard.vue         # SVG canvas, keyboard shortcuts, pan/zoom centering
-    Toolbar.vue            # Left toolbar (tools, canvas settings, color indicators)
-    ColorPalette.vue       # Color picker popover
-    SelectionOverlay.vue   # Selection bounding box + resize handles
-    StrokeRenderer.vue     # Renders a single stroke as SVG
-    composables/
-      useDrawing.ts        # Mouse interaction engine (draw, select, move, resize)
-      useI18n.ts           # Locale and theme provide/inject
-    stores/
-      canvas.ts            # Main store (strokes, colors, pan/zoom, undo, clipboard)
-      tools.ts             # Active tool state
-    utils/
-      geometry.ts          # Hit testing, star/triangle vertices, bounding box
-      svg.ts               # Stroke-to-SVG element conversion
-      i18n.ts              # zh-CN / en-US dictionaries
-    types/
-      index.ts             # TypeScript types and default constants
-    style.css              # CSS custom properties (themes)
-```
+
+### Internationalization
+
+UI text is provided for `zh-CN` and `en-US`. Pass `locale` to switch; unknown values fall back to `zh-CN`. The dictionary lives in `src/components/painter/utils/i18n.ts` and can be extended with additional locales.
+
+---
 
 ## Development
 
 ```bash
-npm run dev     # Start dev server
-npm run build   # Type-check and build for production
-npm run preview # Preview production build
+npm run dev        # Start the Vite dev server (demo page)
+npm run build      # Type-check (vue-tsc) and build the library bundle
+npm run build:demo # Build the standalone demo page into ./dist-demo
+npm run preview    # Preview the library production build
+npm run lint:check # Run ESLint
+npm run typecheck  # Type-check only
 ```
 
+## Building
+
+The library build uses `vite.config.ts` (lib mode). `npm run build` produces:
+
+| File | Description |
+|------|-------------|
+| `dist/xiaodao-painter.es.js` | ES module (for bundlers) |
+| `dist/xiaodao-painter.umd.js` | UMD bundle (for direct `<script>` usage) |
+| `dist/xiaodao-painter.css` | Extracted stylesheet |
+| `dist/types/` | TypeScript declaration files |
+
+`npm run build:demo` builds a standalone demo site via `vite.demo.config.ts` into `dist-demo/` (git-ignored, same as `dist`).
+
+---
+
+## Roadmap
+
+### Near-term
+
+- [x] Pencil, shape, text drawing with selection & transform
+- [x] Pan & zoom, undo/redo, internal clipboard
+- [x] Color system, light/dark themes, i18n
+- [ ] Export to PNG / SVG / JSON
+- [ ] Shape-level snapping & alignment guides
+
+### Mid-term
+
+- [ ] Multi-page / multi-layer support
+- [ ] Image embedding
+- [ ] Cloud save / load integration
+
+### Long-term
+
+- [ ] Collaborative editing
+- [ ] Plugin system for custom shape renderers
+
+---
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Framework | Vue 3 (Composition API + `<script setup>`) | ^3.5 |
+| Build | Vite | ^8.0 |
+| Language | TypeScript (strict) | ~6.0 |
+| Rendering | SVG 2D (DOM) | - |
+| Type Checker | vue-tsc | ^3.3 |
+| Package Manager | npm / pnpm | - |
+| CSS | Scoped CSS + CSS Custom Properties | - |
+
+---
+
 ## License
 
-MIT
+This project is licensed under the MIT License: see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "xiaodao-painter",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A Vue 3 component for drawing on the canvas",
   "type": "module",
   "license": "MIT",
   "homepage": "https://xiaodaozhi.com/xiaodao-painter.html",
   "keywords": [
     "vue",
+    "vue3",
+    "vue-component",
+    "whiteboard",
     "canvas",
-    "drawing",
-    "painter"
+    "draw",
+    "drawing-board",
+    "paint",
+    "sketch",
+    "annotation",
+    "手写板",
+    "白板",
+    "画布",
+    "画板",
+    "绘图",
+    "手绘",
+    "批注",
+    "电子白板"
   ],
   "files": [
     "dist"