# Product Specification: HoverBoard

## 1. Tổng quan sản phẩm (Product Overview)
* **Mục tiêu:** Ứng dụng Menu Bar trên macOS, cung cấp các công cụ hỗ trợ thuyết trình (Vẽ, Zoom, Highlight, Spotlight) tức thì qua phím tắt toàn cục (Global Hotkeys) mà không làm gián đoạn phần mềm đang chia sẻ màn hình (Zoom, Google Meet, MS Teams, v.v.).
* **Target OS:** macOS 14.0 (Sonoma) trở lên (Tận dụng `ScreenCaptureKit` API).
* **Kiến trúc:** Menu Bar App + Transparent Overlay Window.

---

## 2. Đặc tả Tính năng cốt lõi (Core Features - MVP)

### 2.1. System & Control (Hệ thống & Cài đặt)
* **Onboarding:** Yêu cầu quyền **Screen Recording** và **Accessibility** ở lần chạy đầu tiên. Có UI hướng dẫn mở System Settings.
* **Menu Bar Icon:** Chứa các menu: *Settings, Enable/Disable App, Quit*.
* **Settings Panel (SwiftUI):**
    * **General:** Khởi động cùng macOS.
    * **Hotkeys:** Tùy chỉnh phím tắt cho Zoom, Draw, Spotlight.
    * **Appearance:** Chỉnh màu sắc, độ dày nét vẽ mặc định.

### 2.2. Draw & Annotate (Vẽ và Ghi chú)
* **Trigger Flow:** Nhấn phím tắt -> Màn hình tối đi 10% (0.1s) -> Con trỏ đổi thành bút -> Hiện Floating Toolbar.
* **Chức năng:**
    * Vẽ tự do (Freehand).
    * Vẽ hình cơ bản (Mũi tên, Hình chữ nhật).
    * Auto-fade (Tùy chọn): Nét vẽ tự động biến mất sau 3-5 giây.
* **Exit Flow:** Nhấn `Esc` hoặc phím tắt lần nữa -> Xóa toàn bộ nét vẽ -> Trả lại quyền click xuyên thấu cho chuột (Click-through).

### 2.3. Screen Zoom (Phóng to cận cảnh)
* **Trigger Flow:** Nhấn phím tắt -> Chụp nhanh (snapshot) màn hình hiện tại.
* **Chế độ Kính lúp (Loupe Mode):** Xuất hiện một vòng tròn quanh con trỏ chuột, hiển thị phần hình ảnh bên dưới được phóng to 200%. Di chuyển chuột đến đâu, kính lúp đi theo đến đó.
* **Exit Flow:** Nhấn `Esc` hoặc Click chuột trái để thoát.

### 2.4. Spotlight (Focus Mode)
* **Trigger Flow:** Nhấn phím tắt.
* **Behavior:** Toàn màn hình phủ lớp overlay đen (opacity 70%). Khoét một lỗ tròn trong suốt quanh con trỏ chuột để làm nổi bật vùng được chỉ định. Vẫn cho phép click xuyên qua để thao tác.
* **Exit Flow:** Nhấn `Esc` hoặc phím tắt lần nữa.

### 2.5. Whiteboard local-only

* Native AppKit infinite canvas, tách biệt hoàn toàn khỏi Freeze mode.
* Hỗ trợ shape, line/arrow, freehand, text, numbered marker, multi-selection,
  move/resize/rotate, group semantics, lock, layer ordering và undo/redo.
* Property panel chỉnh stroke/fill, opacity, width, roughness, dash, hachure,
  rounded corners, font family, alignment và hyperlink.
* Text multiline có wrapping, container text và arrow label; connector snap/bind
  vào shape và tự cập nhật khi diagram thay đổi.
* Quản lý nhiều board với autosave atomic và tự động migrate
  `Whiteboard.json` cũ sang `WhiteboardLibrary.json` có version; hỗ trợ rename,
  duplicate, switch và delete board.
* Export PNG vùng đang nhìn, SVG toàn bộ nội dung và file `.excalidraw`
  editable. Clipboard cung cấp native data, Excalidraw JSON và SVG; có thể paste
  trực tiếp Excalidraw JSON. Element chưa hỗ trợ được giữ lại để re-export.
* Dữ liệu chỉ lưu local; không có account, cloud hoặc collaboration.

---

## 3. Kiến trúc Kỹ thuật (Technical Architecture)

### 3.1. Framework & API
* **Ngôn ngữ:** Swift, SwiftUI (UI Settings), AppKit (Window Management).
* **Overlay Window:**
    * Sử dụng `NSWindow` với cấu hình: `styleMask = .borderless`, `level = .screenSaver`, `backgroundColor = .clear`, `hasShadow = false`.
    * Quản lý trạng thái tương tác qua thuộc tính `ignoresMouseEvents`.
* **Global Hotkey:** Tích hợp package [KeyboardShortcuts](https://github.com/sindresorhus/KeyboardShortcuts).
* **Screen Capture:** Sử dụng `ScreenCaptureKit` hoặc `CGWindowListCreateImage`.
* **Rendering:** `Core Graphics` (`CGContext`) trên custom `NSView` để xử lý mượt mà sự kiện `mouseDown`, `mouseDragged`.

---

## 4. Quản trị Rủi ro (Risk Management)

| Rủi ro | Giải pháp |
| :--- | :--- |
| **Hỗ trợ Đa màn hình (Multi-monitor)** | Kiểm tra vị trí con trỏ chuột (`NSEvent.mouseLocation`) và khởi tạo Overlay Window trên đúng màn hình (`NSScreen`) đang active. |
| **Memory Leak khi vẽ** | Giới hạn mảng lưu trữ điểm (points) cho tính năng Undo (tối đa 20 steps). Giải phóng memory ngay lập tức khi gọi hàm Clear/Exit. |
| **Xung đột phím tắt** | Cung cấp UI cho phép người dùng tự đổi phím tắt nếu bị trùng với hệ thống hoặc app khác. |

---

## 5. Roadmap Triển khai

* **Giai đoạn 1 (Tuần 1):** Setup project, cấu hình quyền macOS, tích hợp thư viện Hotkey, dựng Overlay Window trong suốt và test click-through.
* **Giai đoạn 2 (Tuần 2):** Triển khai Drawing Core (Vẽ tự do, đổi màu, Undo, Clear).
* **Giai đoạn 3 (Tuần 3):** Xây dựng tính năng Kính lúp (Zoom) và Spotlight. Xử lý triệt để logic đa màn hình.
* **Giai đoạn 4 (Tuần 4):** Hoàn thiện SwiftUI Settings Panel, test hiệu năng, sửa bug và đóng gói.
