Micro Loop Documentation

1. Mục tiêu của extension

ToolPuff Micro Loop giúp bạn học vi mô (micro-learning) ngay trong quá trình lướt web bằng các overlay nhỏ, gọn và ít gây phân tâm.

Extension hiện có 4 phần:

• Vocabulary Progress Bar
• Code Snippet Looping
• Random Fact & Trivia
• Personal Affirmation

2. Cấu trúc giao diện tổng thể

Khi bấm icon extension, popup có 2 tab:

• Overlay: bật/tắt các chủ đề và chỉnh nội dung từng chủ đề.
• Manage: quản lý màu sắc, module hiển thị, hidden items, custom libraries, import/export.

3. Tab Overlay (cài đặt hiển thị chính)

3.1 Global control

Quản lý toàn bộ Overlay:

• Display + pill trạng thái ON/OFF hiển thị trạng thái hiện tại của hệ thống overlay (đang bật hoặc tắt).
• Nút Pause All Overlays / Resume All Overlays cho phép điều khiển nhanh toàn bộ overlay trên trang.

3.2 Vocabulary Progress Bar

Những mục trong phần cài đặt:

• Checkbox bật/tắt: dùng để kích hoạt hoặc tắt nhanh tính năng thanh từ vựng.
• Nguồn nội dung (Content Library & Custom List): khu vực để chọn hoặc quản lý nội dung sẽ hiển thị trên thanh từ vựng. Bạn có thể dùng thư viện có sẵn hoặc nhập danh sách riêng.

Các thiết lập:

• Mode:
  • Library: dùng thư viện có sẵn hoặc custom library đã import.
  • Custom: dùng nội dung tự nhập trong textarea.
• Library: chọn thư viện khi đang ở mode Library.
• Textarea: dùng để xem nội dung của Library khi ở mode Library hoặc để nhập nội dung khi ở mode Custom. Mỗi dòng tương ứng với một item.

Cách hiển thị khi chạy trên website:

• Một thanh mảnh xuất hiện ở đỉnh trang, chạy từ trái sang phải giống như một thanh tiến trình.
• Các item từ vựng di chuyển theo thanh, lần lượt xuất hiện trên thanh này.
• Di chuột vào một item từ vựng: animation sẽ tạm dừng để dễ đọc nội dung.
• Nút × trên item: cho phép ẩn item đó khỏi vòng lặp hiển thị. Item bị ẩn sẽ được đưa vào danh sách Hidden Items.

3.3 Code Snippet Looping

Những mục trong phần cài đặt

• Checkbox bật/tắt module
• Every (sec): thiết lập khoảng thời gian để chuyển sang snippet tiếp theo (tính bằng giây)
• Position (Fixed): vị trí hiển thị của thanh code. Mặc định cố định ở đáy trang (Bottom) và không thể thay đổi.
• Nguồn nội dung (Content Library & Custom List): khu vực để chọn hoặc quản lý danh sách snippet sẽ hiển thị. Bạn có thể sử dụng thư viện có sẵn hoặc nhập danh sách riêng.

Cách hiển thị khi chạy trên website

• Thanh code luôn cố định ở đáy trang.
• Nút Skip: bỏ qua snippet hiện tại và ẩn nó khỏi vòng lặp hiển thị. Snippet này sẽ được đưa vào danh sách Hidden Items của phần Code.
• Nút Hide: ẩn toàn bộ thanh code.
• Sau khi đã Hide, một nút nổi nhỏ “Code” ở góc dưới trang sẽ xuất hiện để bạn mở lại thanh code bất cứ lúc nào.

3.4 Random Fact & Trivia

Những mục trong phần cài đặt

• Checkbox bật/tắt module
• Every (sec)
• Position
• Khối Content Library & Custom List

Position hỗ trợ: Top right, Top left, Bottom right, Bottom left

Cách hiển thị khi chạy trên website

• Popup trivia xuất hiện theo chu kỳ.
• Nút × trên popup: ẩn item đó khỏi vòng lặp (đưa vào Hidden Items của Trivia).

3.5 Personal Affirmation

Những mục trong phần cài đặt

• Checkbox bật/tắt module
• Every (sec)
• Position mode: Random hoặc Fixed
• Fixed position (chỉ bật khi Position mode = Fixed)
• Khối Content Library & Custom List

Fixed position hỗ trợ: Bottom right, Bottom left, Top right, Top left

Cách hiển thị khi chạy trên website

• Popup affirmation xuất hiện theo chu kỳ.
• Nếu Random: vị trí thay đổi ngẫu nhiên trong các góc.
• Nếu Fixed: luôn ở vị trí đã chọn.
• Nút ×: ẩn item khỏi vòng lặp (đưa vào Hidden Items của Affirmation).

3.6 Mode Library vs Custom

Mỗi module đều có 2 mode:

Custom draft thông minh:

• Mỗi module có một custom draft riêng.
• Khi bạn đổi Library -> Custom, extension khôi phục lại custom draft đã soạn trước đó, không bị ghi đè bởi library.
• Khi đổi Custom -> Library, custom draft vẫn được giữ lại.

4. Tab Manage (quản lý dữ liệu và giao diện)

4.1 Overlay Colors

• Restore Defaults: trả màu về mặc định.
• Nhóm màu theo module:
  • Vocabulary: Track, Text, Box, Border
  • Code Snippet: Accent, Text, Box, Border
  • Trivia: Text, Box, Border
  • Affirmation: Text, Box, Border

Lưu ý: Chỉnh xong cần bấm Save Settings để lưu chính thức.

4.2 View Options (hide modules you do not use)

Mục đích: Ẩn bớt card trong tab Overlay để popup gọn hơn.

• Checkbox theo từng module trong Visible Modules In Settings
• Nút Show all: hiện lại toàn bộ module card trong popup.

Lưu ý: Chỉ ảnh hưởng giao diện popup, không tự động tắt module runtime.

4.3 Hidden Items

Hiển thị danh sách item đã bị ẩn theo từng module.

• Restore (từng item): cho item đó xuất hiện lại trong vòng lặp.
• Restore All (theo từng module): khôi phục toàn bộ hidden items của module.

4.4 Custom Libraries

Hiển thị custom libraries theo từng module.

• Nút Delete: Chỉ xóa được custom library.
• Nếu library bị xóa đang được sử dụng: Extension tự chuyển sang library hợp lệ khác để tránh lỗi.

4.5 Backup & Library Pack

A) Backup (settings + hidden + custom)

• Export Backup / Import Backup
• Bao gồm: module on/off, timing/position, color settings, item list, custom drafts, hidden items, custom libraries.
• Dùng khi chuyển máy hoặc lưu trạng thái cá nhân.

B) Library Pack (custom libraries only)

• Export Library Pack / Import Library Pack
• Chỉ gồm các thư viện bạn tự tạo/import thêm (custom libraries).

Không chứa: on/off module, timing/position, màu sắc, hidden items, custom drafts.

Vì vậy import Library Pack không ghi đè cấu hình hiện tại.

Khi nào dùng Library Pack

• Muốn chia sẻ bộ từ vựng/snippet/fact/affirmation cho người khác.
• Muốn nhập thêm nội dung mới nhưng giữ nguyên setup đang dùng.
• Muốn tách "nội dung học" khỏi "cài đặt hiển thị".

Các bước Import Library Pack

1. Mở popup extension.
2. Vào tab Manage.
3. Mở mục Backup & Library Pack.
4. Bấm Import Library Pack.
5. Chọn file JSON library pack.
6. Extension đọc file và thêm các thư viện hợp lệ vào danh sách custom.

Cơ chế hợp nhất khi import

• Import là merge (gộp thêm), không reset.
• Có chống duplicate: Nếu trùng feature + label + items, thư viện đó sẽ bị bỏ qua.
• Nếu file có nhiều library hợp lệ, extension sẽ báo số lượng đã thêm (ví dụ Imported 3 libraries).

4.6 Format JSON & Validation

File mẫu tối thiểu:

{
  "packVersion": 1,
  "type": "toolpuff-library-pack",
  "libraries": [
    {
      "feature": "vocab",
      "label": "My Daily English",
      "items": ["resilient - ...", "insight - ..."]
    },
    {
      "feature": "trivia",
      "label": "Space Facts",
      "items": ["Saturn has over 140 moons.", "..."]
    }
  ]
}

Quy tắc validation

Mỗi library phải có:

• feature: một trong vocab | code | trivia | affirmation
• label: chuỗi không rỗng
• items: mảng item, có ít nhất 1 item không rỗng

Nếu sai:

• Library đó bị bỏ qua.
• Nếu toàn bộ không hợp lệ -> báo lỗi Library pack import failed.

Lỗi thường gặp

5. Ý nghĩa từng button (tổng hợp nhanh)

6. Quy trình sử dụng đề xuất (best practice)

1. Bật module cần dùng trong tab Overlay.
2. Chọn Library để chạy nhanh ban đầu.
3. Chuyển dần sang Custom cho nội dung cá nhân.
4. Tinh chỉnh màu ở tab Manage để dễ đọc và ít gây mỏi mắt.
5. Dùng Hidden Items để loại bớt item đã thuộc.
6. Mỗi tuần export 1 bản Backup.

7. Troubleshooting chi tiết

7.1 Overlay không hiện

1. Global state có đang OFF không (Resume All Overlays).
2. Module checkbox có bật không.
3. Có vô tình hide code bar không (bấm nút Code để hiện lại).
4. Reload tab web.
5. Reload extension tại chrome://extensions.

7.2 Import không thành công

• Đảm bảo đúng type: Backup (toolpuff-user-backup) hoặc Library Pack (toolpuff-library-pack).
• File JSON không lỗi cú pháp.
• Nội dung library có item hợp lệ (không rỗng).

7.3 Đổi Library/Custom thấy nội dung "không như mong đợi"

• Kiểm tra Mode hiện tại.
• Trong mode Library, textarea phản ánh library đang chọn.
• Trong mode Custom, textarea phản ánh custom draft riêng.
• Bấm Save Settings sau mọi thay đổi.

7.4 Màu không cập nhật

• Chỉnh màu ở `Manage > Overlay Colors`.
• Bấm Save Settings.
• Nếu cần, reload tab hiện tại.