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.
• 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.