@pixel-normal-edit/mcp 2.0.7 → 2.0.10

package/rules/README.md

@@ -0,0 +1,403 @@
+# Rules Module — Báo cáo hoạt động
+
+## Tổng quan
+
+Module `rules/` là **bộ não điều khiển** của MCP Firebase Bridge. Nó đảm bảo agent AI **không thể làm bậy** — mọi thao tác vẽ đều phải tuân theo quy trình đã định sẵn.
+
+---
+
+## Cấu trúc thư mục
+
+```
+rules/
+├── index.js           # Module aggregator — import tất cả và export registerAll()
+├── rules.js           # Định nghĩa rules: naming, workflow steps, constraints
+├── workflow.js        # Workflow engine — quản lý trạng thái từng bước
+└── prerequisites.js   # 7 MCP Tools để agent tương tác với workflow
+```
+
+---
+
+## Luồng hoạt động (Workflow)
+
+### 1. Agent bắt đầu bằng `workflow_start`
+
+```
+Agent → workflow_start()
+       ↓
+Workflow Engine khởi tạo 9 bước:
+  [create_canvas → name_canvas → resize_canvas → enable_animation → 
+   setup_layers → prepare_colors → draw → review → finalize]
+       ↓
+Trả về: "Bước hiện tại: Tạo canvas"
+```
+
+### 2. Agent thực hiện từng bước
+
+Mỗi bước có **3 tool** liên quan:
+
+| Tool | Mục đích | Khi nào dùng |
+|------|----------|--------------|
+| `workflow_validate` | Kiểm tra có được phép làm bước này không | **TRƯỚC** mỗi thao tác |
+| `*_tools` (vd: `canvas_resize`) | Thực hiện thao tác thật | Sau khi validate OK |
+| `workflow_advance` | Đánh dấu hoàn thành, chuyển bước tiếp theo | **SAU** khi thao tác thành công |
+
+**Ví dụ thực tế — Bước "Đặt tên canvas":**
+
+```
+Agent → workflow_validate(stepId: "name_canvas")
+       ↓
+Workflow Engine kiểm tra:
+  - Đang ở bước 2? ✓
+  - Bước 1 đã hoàn thành? ✓
+       ↓
+Trả về: "✅ Bạn có thể thực hiện name_canvas"
+       ↓
+Agent → validate_canvas_name(name: "Bức tranh 1")
+       ↓
+Trả về: "✅ Tên hợp lệ!"
+       ↓
+Agent → workspace_rename_tab(tabId: "...", name: "Bức tranh 1")
+       ↓
+Thực hiện đổi tên thành công
+       ↓
+Agent → workflow_advance()
+       ↓
+Workflow Engine:
+  - Đánh dấu "name_canvas" = completed
+  - Chuyển sang bước 3: "Resize canvas"
+       ↓
+Trả về: "✅ Hoàn thành: Đặt tên canvas. Bước tiếp theo: Resize canvas"
+```
+
+### 3. Nếu agent làm sai thứ tự → BỊ CHẶN
+
+```
+Agent → draw_pixel(x: 10, y: 10, color: "#ff0000")  # ❌ Vẽ trước khi tạo canvas!
+       ↓
+(Nếu có middleware kiểm tra workflow)
+       ↓
+Trả về: "⛔ Bạn chưa thể thực hiện 'draw'. 
+         Trước hết hãy hoàn thành: Tạo canvas"
+```
+
+---
+
+## 7 Workflow Tools (trong `prerequisites.js`)
+
+### 1. `workflow_start`
+**Mục đích:** Khởi tạo workflow mới  
+**Tham số:** Không có  
+**Trả về:** Trạng thái workflow ban đầu + bước đầu tiên cần làm
+
+```json
+{
+  "content": [{
+    "type": "text",
+    "text": "🚀 Workflow đã bắt đầu!\n📋 Tiến trình vẽ:\n⬜ Tạo canvas\n🔄 Đặt tên canvas ← ĐANG LÀM\n..."
+  }]
+}
+```
+
+### 2. `workflow_status`
+**Mục đích:** Xem tiến trình hiện tại  
+**Tham số:** Không có  
+**Trả về:** Danh sách các bước với trạng thái (✅/🔄/⬜)
+
+### 3. `workflow_advance`
+**Mục đích:** Đánh dấu hoàn thành bước hiện tại, chuyển sang bước tiếp theo  
+**Tham số:** Không có  
+**Trả về:** Thông báo bước vừa hoàn thành + bước tiếp theo
+
+### 4. `workflow_validate`
+**Mục đích:** Kiểm tra agent có được phép thực hiện hành động không  
+**Tham số:**
+- `stepId` (string): ID bước muốn kiểm tra (vd: "draw", "resize_canvas")
+
+**Trả về:**
+- Nếu OK: `"✅ Bạn có thể thực hiện 'draw'. Hãy tiếp tục!"`
+- Nếu sai thứ tự: `"⛔ Bạn chưa thể thực hiện 'draw'. Trước hết hãy hoàn thành: Tạo canvas"`
+
+### 5. `workflow_reset`
+**Mục đích:** Reset workflow về đầu (xóa toàn bộ tiến trình)  
+**Tham số:** Không có  
+**Trả về:** `"🔄 Workflow đã được reset. Hãy bắt đầu lại từ đầu."`
+
+### 6. `validate_canvas_name`
+**Mục đích:** Kiểm tra tên canvas có hợp lệ không  
+**Tham số:**
+- `name` (string): Tên canvas muốn kiểm tra
+
+**Quy tắc:**
+- 3-64 ký tự
+- Chỉ gồm chữ, số, `_`, `-`, khoảng trắng
+- Ví dụ hợp lệ: "Bức_tranh_1", "My Canvas 2024"
+
+### 7. `validate_canvas_size`
+**Mục đích:** Kiểm tra kích thước canvas có nằm trong giới hạn không  
+**Tham số:**
+- `width` (int): Chiều rộng
+- `height` (int): Chiều cao
+
+**Giới hạn:** 8x8 đến 1024x1024 pixels
+
+---
+
+## 9 Workflow Steps (định nghĩa trong `rules.js`)
+
+| # | Step ID | Label | Description |
+|---|---------|-------|-------------|
+| 1 | `create_canvas` | Tạo canvas | Tạo tab mới với kích thước phù hợp |
+| 2 | `name_canvas` | Đặt tên canvas | Đặt tên cho canvas (3-64 ký tự) |
+| 3 | `resize_canvas` | Resize canvas | Điều chỉnh kích thước canvas nếu cần |
+| 4 | `enable_animation` | Bật animation | Bật chế độ animation nếu cần nhiều frame |
+| 5 | `setup_layers` | Thiết lập layers | Tạo/sắp xếp layers trước khi vẽ |
+| 6 | `prepare_colors` | Chuẩn bị màu sắc | Chọn màu chính/phụ trước khi vẽ |
+| 7 | `draw` | Vẽ | Thực hiện vẽ theo đúng kỹ thuật |
+| 8 | `review` | Kiểm tra | Xem lại kết quả sau khi vẽ |
+| 9 | `finalize` | Hoàn tất | Lưu và hoàn tất tác phẩm |
+
+---
+
+## Các loại Rules (trong `rules.js`)
+
+### 1. Naming Rules (`NAMING_RULES`)
+
+Quy tắc đặt tên cho các đối tượng:
+
+| Object | Pattern | Example |
+|--------|---------|---------|
+| Canvas/Tab | `^[A-Za-z0-9_\-\sÀ-ỹ]{3,64}$` | "Bức_tranh_1" |
+| Stamp | `^[a-z][a-z0-9_]{2,32}$` | "my_tree_01" |
+| Anchor | `^[a-z][a-z0-9_]{2,32}$` | "head_top" |
+
+### 2. Workflow Steps (`WORKFLOW_STEPS`)
+
+Danh sách 9 bước bắt buộc (xem bảng ở mục trên).
+
+### 3. Drawing Constraints (`DRAWING_CONSTRAINTS`)
+
+| Constraint | Value |
+|------------|-------|
+| Max canvas size | 1024x1024 |
+| Min canvas size | 8x8 |
+| Allowed colors | Tất cả hex colors |
+| Max stamp name length | 32 ký tự |
+| Max anchor name length | 32 ký tự |
+
+---
+
+## Workflow Engine (`workflow.js`)
+
+### State Management
+
+Workflow engine lưu trạng thái **in-memory** theo session:
+
+```javascript
+sessions = new Map([
+  "session-id-1": {
+    currentStepIndex: 2,
+    steps: [
+      { id: "create_canvas", label: "Tạo canvas", status: "completed" },
+      { id: "name_canvas", label: "Đặt tên canvas", status: "completed" },
+      { id: "resize_canvas", label: "Resize canvas", status: "in_progress" },
+      // ...
+    ],
+    completedSteps: ["create_canvas", "name_canvas"],
+    startedAt: 1234567890
+  }
+])
+```
+
+### Các hàm chính
+
+| Hàm | Mục đích |
+|------|----------|
+| `start(sessionId)` | Khởi tạo workflow mới |
+| `getState(sessionId)` | Lấy toàn bộ trạng thái |
+| `getCurrentStep(sessionId)` | Lấy bước hiện tại |
+| `validateStep(sessionId, stepId)` | Kiểm tra có được phép làm bước này không |
+| `advance(sessionId)` | Hoàn thành bước hiện tại, chuyển sang bước tiếp |
+| `reset(sessionId)` | Reset workflow về đầu |
+| `getProgressReport(sessionId)` | Lấy báo cáo tiến trình dạng text |
+
+### Logic Validation
+
+```
+validateStep(sessionId, stepId):
+  1. Nếu chưa start workflow → TỪ CHỐI
+  2. Nếu workflow đã hoàn thành → TỪ CHỐI
+  3. Nếu stepId đã hoàn thành → CHO PHÉP (với warning)
+  4. Nếu stepId đúng là bước hiện tại → CHO PHÉP
+  5. Nếu stepId nằm ở tương lai → TỪ CHỐI (với hướng dẫn bước hiện tại)
+```
+
+---
+
+## Cách sử dụng cho Agent
+
+### Scenario 1: Vẽ một hình tròn đơn giản
+
+```
+1. workflow_start()
+   → "Bước 1: Tạo canvas"
+
+2. validate_canvas_size(width: 32, height: 32)
+   → "✅ Kích thước 32x32 hợp lệ!"
+
+3. workspace_create_tab(width: 32, height: 32)
+   → Tạo canvas thành công
+
+4. workflow_validate(stepId: "name_canvas")
+   → "✅ Bạn có thể thực hiện name_canvas"
+
+5. validate_canvas_name(name: "Hình tròn")
+   → "✅ Tên hợp lệ!"
+
+6. workspace_rename_tab(tabId: "...", name: "Hình tròn")
+   → Đổi tên thành công
+
+7. workflow_advance()
+   → "✅ Hoàn thành: Đặt tên canvas. Bước tiếp theo: Resize canvas"
+
+8. workflow_validate(stepId: "resize_canvas")
+   → "✅ Bạn có thể thực hiện resize_canvas"
+
+9. canvas_resize(width: 64, height: 64)
+   → Resize thành công
+
+10. workflow_advance()
+    → Chuyển sang bước "Bật animation"
+
+11. workflow_validate(stepId: "enable_animation")
+    → "✅ Bạn có thể thực hiện enable_animation"
+
+12. animation_enable(enabled: false)  # Không cần animation
+    → OK
+
+13. workflow_advance()
+    → Chuyển sang bước "Thiết lập layers"
+
+14. workflow_validate(stepId: "setup_layers")
+    → "✅ Bạn có thể thực hiện setup_layers"
+
+15. layer_add()
+    → Thêm layer mới
+
+16. workflow_advance()
+    → Chuyển sang bước "Chuẩn bị màu sắc"
+
+17. workflow_validate(stepId: "prepare_colors")
+    → "✅ Bạn có thể thực hiện prepare_colors"
+
+18. color_set(primary: "#ff0000")
+    → Đặt màu đỏ
+
+19. workflow_advance()
+    → Chuyển sang bước "Vẽ" ← ĐÂY LÀ BƯỚC QUAN TRỌNG
+
+20. workflow_validate(stepId: "draw")
+    → "✅ Bạn có thể thực hiện draw"
+
+21. draw_circle(cx: 32, cy: 32, r: 20, color: "#ff0000")
+    → Vẽ hình tròn thành công
+
+22. workflow_advance()
+    → Chuyển sang bước "Kiểm tra"
+
+23. workflow_validate(stepId: "review")
+    → "✅ Bạn có thể thực hiện review"
+
+24. query_snapshot()
+    → Xem kết quả vẽ
+
+25. workflow_advance()
+    → Chuyển sang bước "Hoàn tất"
+
+26. workflow_validate(stepId: "finalize")
+    → "✅ Bạn có thể thực hiện finalize"
+
+27. workspace_save()
+    → Lưu tác phẩm
+
+28. workflow_advance()
+    → "🎉 Hoàn tất tất cả các bước!"
+```
+
+### Scenario 2: Agent cố gắng vẽ trước khi tạo canvas
+
+```
+1. workflow_start()
+   → "Bước 1: Tạo canvas"
+
+2. draw_pixel(x: 10, y: 10, color: "#ff0000")  # ❌ Sai thứ tự!
+   → (Nếu có middleware kiểm tra)
+   → "⛔ Bạn chưa thể thực hiện 'draw'. 
+      Trước hết hãy hoàn thành: Tạo canvas"
+```
+
+---
+
+## Lưu ý quan trọng
+
+1. **Workflow là per-session:** Mỗi session có workflow riêng, không ảnh hưởng lẫn nhau.
+2. **Có thể quay lại bước cũ:** Nếu agent đã hoàn thành bước 3 và muốn làm lại, `validateStep` sẽ cho phép nhưng có cảnh báo.
+3. **Workflow không tự động chặn tool:** Tool `draw_pixel` vẫn chạy được nếu agent gọi trực tiếp. Tuy nhiên, agent được hướng dẫn **PHẢI** gọi `workflow_validate` trước mỗi thao tác.
+4. **Có thể reset:** Dùng `workflow_reset` để bắt đầu lại từ đầu nếu cần.
+
+---
+
+## Cách thêm Rule mới
+
+### Thêm Naming Rule mới
+
+```javascript
+// rules.js
+const NAMING_RULES = {
+  // ... existing rules
+  newObject: {
+    pattern: /^[a-z]{3,16}$/,
+    message: 'Tên phải 3-16 ký tự, chỉ chữ thường',
+    example: 'myobject',
+  },
+};
+
+// Thêm validator
+function validateNewObjectName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên không được để trống' };
+  }
+  if (!NAMING_RULES.newObject.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.newObject.message };
+  }
+  return { valid: true };
+}
+```
+
+### Thêm Workflow Step mới
+
+```javascript
+// rules.js
+const WORKFLOW_STEPS = [
+  // ... existing steps
+  { id: 'new_step', label: 'Bước mới', description: 'Mô tả bước mới' },
+];
+
+// prerequisites.js — Thêm tool validate nếu cần
+registerTool(server, 'validate_new_step', 'Kiểm tra...', {...}, (p) => {...});
+```
+
+---
+
+## Tóm tắt
+
+Module `rules/` đảm bảo:
+
+✅ Agent **bắt buộc** tuân theo thứ tự 9 bước  
+✅ Tất cả tên đều **hợp lệ** theo quy tắc  
+✅ Kích thước canvas **nằm trong giới hạn**  
+✅ Agent **không thể bỏ qua** bước nào  
+✅ Có thể **kiểm tra tiến trình** bất cứ lúc nào  
+✅ Có thể **reset** nếu cần làm lại  
+
+**Mục tiêu:** Không còn tình trạng "agent muốn gì làm nấy" — mọi thao tác đều có **rule engine** giám sát.

package/rules/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * rules/index.js — Rules Module Aggregator
+ *
+ * Aggregates và export tất cả các rules, workflow engine, và prerequisite tools.
+ *
+ * Module này cung cấp:
+ *   1. rules.js         — Định nghĩa rules (naming, constraints, validators)
+ *   2. workflow.js      — Workflow engine (quản lý thứ tự bước)
+ *   3. prerequisites.js — MCP Tools cho workflow (start, status, advance, validate)
+ *
+ * Cách thêm rule mới:
+ *   - Thêm vào rules.js (NAMING_RULES, WORKFLOW_STEPS, DRAWING_CONSTRAINTS)
+ *   - Nếu cần logic phức tạp, tạo file mới trong rules/ và import vào đây
+ */
+
+const rules = require('./rules');
+const workflow = require('./workflow');
+const prerequisites = require('./prerequisites');
+
+/**
+ * Register tất cả workflow/prerequisite tools lên MCP server
+ * @param {McpServer} server
+ */
+function registerAll(server) {
+  prerequisites.register(server);
+}
+
+module.exports = {
+  rules,
+  workflow,
+  prerequisites,
+  registerAll,
+};

package/rules/prerequisites.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * prerequisites.js — Prerequisites Check (Điều kiện để chạy)
+ *
+ * Đây là MCP Tool để agent gọi trước khi bắt đầu vẽ.
+ * Nó sẽ kiểm tra mọi điều kiện tiên quyết và trả về hướng dẫn chi tiết.
+ *
+ * QUAN TRỌNG: Agent BẮT BUỘC phải gọi tool này TRƯỚC TIÊN
+ * trước khi làm bất kỳ thao tác vẽ nào.
+ */
+
+const { z } = require('zod');
+const { validateCanvasName, validateCanvasSize, DRAWING_CONSTRAINTS, WORKFLOW_STEPS } = require('./rules');
+const workflow = require('./workflow');
+const { registerTool } = require('../core/server');
+
+/**
+ * Register workflow/prerequisite tools on the MCP server
+ * @param {McpServer} server
+ */
+function register(server) {
+  // ── Tool 1: workflow_start — Bắt đầu workflow ─────────────────────────
+  registerTool(server, 'workflow_start',
+    `🚀 BẮT BUỘC: Gọi tool này ĐẦU TIÊN trước khi vẽ bất cứ thứ gì.
+Tool này khởi tạo một workflow vẽ với các bước tuần tự.
+Agent PHẢI làm theo đúng thứ tự các bước.
+
+Các bước workflow:
+1. create_canvas  — Tạo canvas mới
+2. name_canvas    — Đặt tên cho canvas
+3. resize_canvas  — Resize nếu cần
+4. enable_animation — Bật animation nếu cần
+5. setup_layers   — Thiết lập layers
+6. prepare_colors — Chuẩn bị màu sắc
+7. draw           — Vẽ (chỉ được vẽ sau các bước trên)
+8. review         — Kiểm tra kết quả
+9. finalize       — Lưu và hoàn tất`,
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const state = workflow.start(session);
+      return {
+        content: [{ type: 'text', text: `🚀 **Workflow đã bắt đầu!**\n\n${workflow.getProgressReport(session)}\n\n---\nBắt đầu với bước: **${state.steps[0].label}** → ${state.steps[0].description}` }]
+      };
+    });
+
+  // ── Tool 2: workflow_status — Xem trạng thái hiện tại ─────────────────
+  registerTool(server, 'workflow_status',
+    'Xem tiến trình workflow hiện tại: đang ở bước nào, đã làm gì, cần làm gì tiếp theo.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const report = workflow.getProgressReport(session);
+      const current = workflow.getCurrentStep(session);
+      if (!current) {
+        return { content: [{ type: 'text', text: '⚠️ Chưa bắt đầu workflow. Gọi **workflow_start** trước.' }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: `${report}\n\n👉 **Đang cần:** ${current.label} — ${current.description}`
+        }]
+      };
+    });
+
+  // ── Tool 3: workflow_advance — Hoàn thành bước hiện tại ───────────────
+  registerTool(server, 'workflow_advance',
+    '✅ Đánh dấu bước hiện tại là hoàn thành và chuyển sang bước tiếp theo. Chỉ gọi SAU KHI đã làm xong bước hiện tại.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const result = workflow.advance(session);
+      if (!result.success) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      if (!result.nextStep) {
+        return { content: [{ type: 'text', text: `🎉 ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: result.message }] };
+    });
+
+  // ── Tool 4: workflow_validate — Kiểm tra trước khi gọi tool ──────────
+  registerTool(server, 'workflow_validate',
+    `🔍 Kiểm tra xem agent có được phép thực hiện một hành động nào đó không.
+  Gọi tool này TRƯỚC khi làm bất kỳ thao tác vẽ nào để đảm bảo đúng thứ tự workflow.
+  
+  Các stepId hợp lệ:
+  - create_canvas
+  - name_canvas
+  - resize_canvas
+  - enable_animation
+  - setup_layers
+  - prepare_colors
+  - draw
+  - review
+  - finalize`,
+    { stepId: z.string().describe('ID của bước muốn kiểm tra (vd: "draw", "resize_canvas")') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const result = workflow.validateStep(session, p.stepId);
+      if (!result.allowed) {
+        return { isError: true, content: [{ type: 'text', text: result.message }] };
+      }
+      return { content: [{ type: 'text', text: result.message || `✅ Bạn có thể thực hiện "${p.stepId}". Hãy tiếp tục!` }] };
+    });
+
+  // ── Tool 5: workflow_reset — Làm lại từ đầu ──────────────────────────
+  registerTool(server, 'workflow_reset',
+    '🔄 Reset workflow về trạng thái ban đầu. Xoá toàn bộ tiến trình đã làm.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      workflow.reset(session);
+      return { content: [{ type: 'text', text: '🔄 Workflow đã được reset. Hãy bắt đầu lại từ đầu.' }] };
+    });
+
+  // ── Tool 6: validate_canvas_name — Kiểm tra tên canvas ───────────────
+  registerTool(server, 'validate_canvas_name',
+    `Kiểm tra tên canvas có hợp lệ không trước khi đặt.
+  Quy tắc: 3-64 ký tự, chỉ gồm chữ, số, _, -, khoảng trắng.
+  Ví dụ: "Bức_tranh_1", "My Canvas 2024"`,
+    { name: z.string().describe('Tên canvas muốn kiểm tra') },
+    (p) => {
+      const result = validateCanvasName(p.name);
+      if (!result.valid) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Tên "${p.name}" hợp lệ!` }] };
+    });
+
+  // ── Tool 7: validate_canvas_size — Kiểm tra kích thước canvas ────────
+  registerTool(server, 'validate_canvas_size',
+    `Kiểm tra kích thước canvas có nằm trong giới hạn cho phép không.
+  Giới hạn: ${DRAWING_CONSTRAINTS.minCanvasSize.width}x${DRAWING_CONSTRAINTS.minCanvasSize.height} đến ${DRAWING_CONSTRAINTS.maxCanvasSize.width}x${DRAWING_CONSTRAINTS.maxCanvasSize.height}`,
+    { width: z.number().int().describe('Chiều rộng'), height: z.number().int().describe('Chiều cao') },
+    (p) => {
+      const result = validateCanvasSize(p.width, p.height);
+      if (!result.valid) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Kích thước ${p.width}x${p.height} hợp lệ!` }] };
+    });
+}
+
+module.exports = { register };

package/rules/rules.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * rules.js — Core Drawing Rules & Constraints
+ *
+ * QUAN TRỌNG: Mọi function trong đây là luật BẮT BUỘC.
+ * Agent KHÔNG được tự ý bỏ qua hay làm sai thứ tự.
+ *
+ * Các rules được chia làm 3 loại:
+ *   1. naming    — Quy tắc đặt tên tab/canvas
+ *   2. workflow  — Quy tắc thứ tự các bước
+ *   3. drawing   — Quy tắc về vẽ (kích thước, màu sắc, v.v.)
+ */
+
+// ── Loại 1: Naming Rules ────────────────────────────────────────────────────
+const NAMING_RULES = {
+  canvasTab: {
+    pattern: /^[A-Za-z0-9_\-\sÀ-ỹ]{3,64}$/,
+    message: 'Tên canvas phải từ 3-64 ký tự, chỉ gồm chữ, số, _, -, và khoảng trắng',
+    example: 'Bức_tranh_1',
+  },
+  stamp: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Tên stamp phải bắt đầu bằng chữ thường, 3-32 ký tự, chỉ gồm a-z, 0-9, _',
+    example: 'my_tree_01',
+  },
+  anchor: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Tên anchor phải bắt đầu bằng chữ thường, 3-32 ký tự',
+    example: 'head_top',
+  },
+};
+
+// ── Loại 2: Workflow Steps (thứ tự bắt buộc) ──────────────────────────────
+const WORKFLOW_STEPS = [
+  { id: 'create_canvas',  label: 'Tạo canvas',          description: 'Tạo tab mới với kích thước phù hợp' },
+  { id: 'name_canvas',    label: 'Đặt tên canvas',      description: 'Đặt tên cho canvas (3-64 ký tự)' },
+  { id: 'resize_canvas',  label: 'Resize canvas',       description: 'Điều chỉnh kích thước canvas nếu cần' },
+  { id: 'enable_animation', label: 'Bật animation',     description: 'Bật chế độ animation nếu cần nhiều frame' },
+  { id: 'setup_layers',   label: 'Thiết lập layers',    description: 'Tạo/sắp xếp layers trước khi vẽ' },
+  { id: 'prepare_colors', label: 'Chuẩn bị màu sắc',    description: 'Chọn màu chính/phụ trước khi vẽ' },
+  { id: 'draw',           label: 'Vẽ',                  description: 'Thực hiện vẽ theo đúng kỹ thuật' },
+  { id: 'review',         label: 'Kiểm tra',            description: 'Xem lại kết quả sau khi vẽ' },
+  { id: 'finalize',       label: 'Hoàn tất',            description: 'Lưu và hoàn tất tác phẩm' },
+];
+
+// ── Loại 3: Drawing Constraints ─────────────────────────────────────────────
+const DRAWING_CONSTRAINTS = {
+  maxCanvasSize: { width: 1024, height: 1024 },
+  minCanvasSize: { width: 8, height: 8 },
+  allowedColors: null, // null = all hex colors allowed
+  maxStampNameLength: 32,
+  maxAnchorNameLength: 32,
+};
+
+// ── Validator Functions ──────────────────────────────────────────────────────
+
+/**
+ * Kiểm tra tên canvas có hợp lệ không
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateCanvasName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên canvas không được để trống' };
+  }
+  if (!NAMING_RULES.canvasTab.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.canvasTab.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Kiểm tra tên stamp có hợp lệ không
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateStampName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên stamp không được để trống' };
+  }
+  if (!NAMING_RULES.stamp.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.stamp.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Kiểm tra kích thước canvas có nằm trong giới hạn không
+ * @param {number} w
+ * @param {number} h
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateCanvasSize(w, h) {
+  const { minCanvasSize, maxCanvasSize } = DRAWING_CONSTRAINTS;
+  if (w < minCanvasSize.width || h < minCanvasSize.height) {
+    return { valid: false, message: `Canvas tối thiểu ${minCanvasSize.width}x${minCanvasSize.height}` };
+  }
+  if (w > maxCanvasSize.width || h > maxCanvasSize.height) {
+    return { valid: false, message: `Canvas tối đa ${maxCanvasSize.width}x${maxCanvasSize.height}` };
+  }
+  return { valid: true };
+}
+
+module.exports = {
+  NAMING_RULES,
+  WORKFLOW_STEPS,
+  DRAWING_CONSTRAINTS,
+  validateCanvasName,
+  validateStampName,
+  validateCanvasSize,
+};