@thanh01.pmt/interactive-quiz-kit 1.0.3 → 1.0.5

package/HEADLESS.md

@@ -0,0 +1,330 @@
+# Chế độ Headless: Sử dụng Logic của `interactive-quiz-kit` mà không cần Giao diện
+
+**`interactive-quiz-kit`** được thiết kế với kiến trúc module hóa, cho phép bạn sử dụng toàn bộ logic lõi của nó một cách độc lập mà không cần đến các thành phần giao diện người dùng React. Chế độ "headless" này lý tưởng cho các trường hợp sử dụng như:
+
+*   Xây dựng một backend để quản lý và tạo quiz.
+*   Tích hợp logic quiz vào một ứng dụng di động (React Native, Flutter,...).
+*   Chạy các script tự động để tạo nội dung hoặc xử lý dữ liệu quiz.
+*   Tích hợp vào các framework JavaScript khác ngoài React.
+
+Tài liệu này sẽ hướng dẫn bạn cách import và sử dụng các tính năng headless chính của thư viện.
+
+## I. Tổng quan các Thành phần Headless
+
+Các thành phần non-UI của thư viện được phân bổ trong các thư mục sau:
+
+| Thư mục/File | Chức năng Chính |
+| :--- | :--- |
+| `types.ts` | **(Cốt lõi)** Định nghĩa tất cả các cấu trúc dữ liệu (interfaces) cho quiz. |
+| `services/` | **(Cốt lõi)** Chứa các service để chạy, quản lý, và đóng gói quiz. |
+| `ai/` | Chứa các flow để tạo nội dung quiz bằng Trí tuệ Nhân tạo. |
+| `utils/idGenerators.ts` | Các hàm tiện ích, ví dụ như tạo ID duy nhất. |
+| `schemas/` | Các file JSON Schema để xác thực cấu trúc dữ liệu của quiz. |
+
+### 1. Chế độ Headless là gì và Tại sao nó quan trọng?
+
+Hãy tưởng tượng thư viện của bạn như một chiếc xe hơi hoàn chỉnh. Giao diện người dùng (`react-ui/`) chính là phần thân vỏ, nội thất, vô lăng, bảng điều khiển—tất cả những gì bạn thấy và tương tác. "Chế độ headless" chính là việc bạn có thể lấy toàn bộ **động cơ, khung gầm, hệ thống truyền động và bộ não điều khiển (ECU)** của chiếc xe đó ra và lắp vào một thân vỏ khác—ví dụ như một chiếc xe tải, một chiếc thuyền, hoặc thậm chí một cỗ máy công nghiệp.
+
+Nói cách khác, **chế độ headless cho phép bạn sử dụng tất cả các logic, quy trình nghiệp vụ, và khả năng xử lý dữ liệu của thư viện mà không cần đến giao diện người dùng React đi kèm.**
+
+**Tại sao nó quan trọng?**
+*   **Linh hoạt tối đa:** Bạn không bị trói buộc vào React. Bạn có thể xây dựng giao diện bằng Vue, Svelte, Angular, hoặc thậm chí là ứng dụng di động native (iOS, Android) và chỉ cần gọi đến logic lõi của thư viện.
+*   **Tự động hóa & Tích hợp Backend:** Bạn có thể chạy các quy trình trên server, ví dụ:
+    *   Một cron job hàng đêm dùng module AI để tự động tạo ra hàng trăm câu hỏi mới và lưu vào cơ sở dữ liệu.
+    *   Xây dựng một API endpoint để quản lý, chỉnh sửa, và xuất bản các bài quiz.
+*   **Tái sử dụng Logic:** Đảm bảo logic nghiệp vụ (ví dụ: cách chấm điểm một câu hỏi) là nhất quán ở mọi nơi, từ web, mobile đến các script nội bộ.
+
+---
+
+### 2. Phân tích chi tiết các Thành phần Headless
+
+Dưới đây là từng thành phần, vai trò, và tầm quan trọng của chúng trong chế độ headless.
+
+#### **A. `types.ts` & `schemas/` - Nền tảng & Quy tắc**
+
+*   **Vai trò:** Là "Hiến pháp" và "Bộ luật" của thư viện. Chúng định nghĩa cấu trúc dữ liệu và các quy tắc mà mọi thành phần khác phải tuân theo.
+*   **Mô tả chi tiết:**
+    *   **`types.ts`:** Đây là file quan trọng nhất. Nó chứa các `interface` TypeScript như `QuizConfig`, `QuizQuestion`, `QuizResult`. Đây là "nguồn chân lý duy nhất" (single source of truth) cho hình dạng của dữ liệu. Bất kỳ hàm nào bạn viết để tương tác với quiz đều sẽ nhận và trả về các kiểu dữ liệu được định nghĩa ở đây.
+    *   **`schemas/`:** Chứa các file JSON Schema. Trong môi trường headless, chúng cực kỳ hữu ích để **xác thực (validate)** dữ liệu. Ví dụ, khi một hệ thống khác gửi cho bạn một file JSON `quiz.json`, bạn có thể dùng schema này để kiểm tra xem file đó có hợp lệ hay không trước khi xử lý.
+*   **Tầm quan trọng:** **Nền tảng (Fundamental)**. Không thể sử dụng thư viện nếu không hiểu các kiểu dữ liệu này.
+
+---
+
+#### **B. `services/QuizEditorService.ts` - Người Thợ Xây**
+
+*   **Vai trò:** Công cụ để **tạo, sửa, xóa, và sắp xếp** các câu hỏi bên trong một đối tượng `QuizConfig`. Đây là service dành cho khâu *biên soạn (authoring)*.
+*   **Mô tả chi tiết:**
+    *   Đây là một lớp (class) bạn khởi tạo với một đối tượng `QuizConfig` ban đầu. Nó sẽ làm việc trên một bản sao sâu (deep copy), đảm bảo không làm thay đổi đối tượng gốc một cách không mong muốn (nguyên tắc immutability).
+    *   **`createNewQuestionTemplate(type)` (Static Method):** Tạo ra một "khuôn mẫu" câu hỏi rỗng với các giá trị mặc định. Rất hữu ích khi bạn muốn thêm một câu hỏi mới.
+    *   **`addQuestion(question)`:** Thêm một câu hỏi vào danh sách.
+    *   **`updateQuestion(updatedQuestion)`:** Cập nhật một câu hỏi đã có dựa trên `id` của nó.
+    *   **`deleteQuestionByIndex(index)`:** Xóa một câu hỏi dựa trên vị trí của nó.
+    *   **`moveQuestion(fromIndex, toIndex)`:** Thay đổi thứ tự các câu hỏi.
+*   **Tầm quan trọng:** **Cốt lõi (Core)** cho bất kỳ tác vụ nào liên quan đến việc quản lý nội dung quiz.
+
+*   **Ví dụ sử dụng:**
+    ```typescript
+    import { QuizEditorService, emptyQuiz } from 'interactive-quiz-kit/services';
+
+    // Bắt đầu với một quiz rỗng
+    let myQuiz = emptyQuiz;
+    const editor = new QuizEditorService(myQuiz);
+
+    // Thêm một câu hỏi True/False
+    const tfQuestion = QuizEditorService.createNewQuestionTemplate('true_false');
+    tfQuestion.prompt = "Trái Đất có phải là một hình cầu hoàn hảo không?";
+    if (tfQuestion.questionType === 'true_false') tfQuestion.correctAnswer = false;
+    
+    myQuiz = editor.addQuestion(tfQuestion);
+
+    // Cập nhật lại tiêu đề quiz
+    myQuiz.title = "Quiz đã được cập nhật bằng code";
+
+    console.log(myQuiz);
+    ```
+
+---
+
+#### **C. `services/QuizEngine.ts` - Nhạc trưởng Điều hành**
+
+*   **Vai trò:** Quản lý toàn bộ vòng đời của một **phiên làm bài quiz thực tế**. Đây là service dành cho khâu *thực thi (runtime)*.
+*   **Mô tả chi tiết:**
+    *   Khởi tạo với một `QuizConfig` và một bộ `callbacks`. Thiết kế dựa trên callback này làm cho nó cực kỳ linh hoạt để tích hợp vào bất kỳ hệ thống nào.
+    *   Nó quản lý trạng thái nội bộ: câu hỏi hiện tại, câu trả lời của người dùng, thời gian còn lại.
+    *   Cung cấp các phương thức công khai (public methods) như `nextQuestion()`, `previousQuestion()`, `submitAnswer()`, và `calculateResults()` để điều khiển luồng làm bài.
+    *   Logic chấm điểm phức tạp cho 12 loại câu hỏi được đóng gói hoàn toàn bên trong `evaluateQuestion`.
+*   **Tầm quan trọng:** **Cốt lõi (Core)** cho bất kỳ ứng dụng nào muốn cho người dùng *làm* bài quiz.
+
+---
+
+#### **D. `ai/flows/` - Bộ não Sáng tạo**
+
+*   **Vai trò:** Cung cấp các hàm `async` để giao tiếp với AI và tự động tạo ra nội dung quiz.
+*   **Mô tả chi tiết:**
+    *   Mỗi file là một "flow" có thể gọi được. Chúng nhận đầu vào có cấu trúc (nhờ `zod`) và trả về kết quả cũng có cấu trúc.
+    *   **`generate...Question`:** Các flow tạo câu hỏi đơn lẻ.
+    *   **`generateQuizPlan` & `generateQuestionsFromQuizPlan`:** Một quy trình 2 giai đoạn mạnh mẽ cho phép tạo ra một bài quiz hoàn chỉnh, cân bằng về chủ đề và độ khó, thay vì chỉ là một mớ câu hỏi ngẫu nhiên.
+*   **Tầm quan trọng:** **Tính năng nâng cao (Advanced Feature)**. Lý tưởng cho các hệ thống muốn tự động hóa việc tạo nội dung.
+
+*   **Ví dụ sử dụng (trong một script backend):**
+    ```typescript
+    import { generateQuizPlan, generateQuestionsFromQuizPlan } from 'interactive-quiz-kit/ai';
+
+    async function generateFullQuiz() {
+      const planInput = {
+        totalQuestions: 5,
+        topics: [{ topic: 'Lịch sử Việt Nam', ratio: 100 }],
+        bloomLevels: [{ level: 'remembering', ratio: 60 }, { level: 'understanding', ratio: 40 }],
+        selectedQuestionTypes: ['multiple_choice', 'true_false']
+      };
+      
+      const plan = await generateQuizPlan(planInput);
+      
+      const quizResult = await generateQuestionsFromQuizPlan({ quizPlan: plan.quizPlan });
+
+      console.log(`${quizResult.generatedQuestions.length} câu hỏi đã được tạo.`);
+      // => Lưu các câu hỏi này vào DB
+    }
+    ```
+
+---
+
+#### **E. `services/` (các file liên quan đến SCORM) & `utils/` - Hộp Dụng cụ & Giao tiếp**
+
+*   **Vai trò:** Cung cấp các công cụ chuyên biệt để hoàn thành các tác vụ cụ thể.
+*   **Mô tả chi tiết:**
+    *   **`SCORMService.ts`:** Một lớp độc lập để nói chuyện với LMS. Nó không biết gì về quiz, chỉ biết về các lệnh SCORM. `QuizEngine` sẽ sử dụng nó.
+    *   **`generateSCORMManifest`, `generateLauncherHTML`:** Các hàm này nhận dữ liệu và trả về các chuỗi văn bản (XML, HTML). Chúng không có tác dụng phụ (side-effect) và hoàn toàn "thuần khiết" (pure), rất phù hợp cho môi trường headless.
+    *   **`idGenerators.ts`:** Cung cấp hàm `generateUniqueId`, một tiện ích nhỏ nhưng cần thiết khi bạn tạo dữ liệu mới.
+*   **Tầm quan trọng:** **Hỗ trợ (Supporting)**. Cần thiết cho các chức năng cụ thể như SCORM hoặc khi cần tạo dữ liệu mới.
+
+Bằng cách kết hợp các thành phần này, bạn có thể xây dựng một hệ thống hoàn chỉnh ở phía backend để tạo, quản lý quiz, và thậm chí mô phỏng các phiên làm bài để kiểm thử mà không cần viết một dòng code giao diện nào.
+
+---
+
+## II. Các Kiểu Dữ liệu (Types) - Nền tảng của Thư viện
+
+Trước khi bắt đầu, bạn cần làm quen với các kiểu dữ liệu chính. Mọi tương tác với thư viện đều xoay quanh chúng.
+
+```typescript
+import { QuizConfig, QuizQuestion, TrueFalseQuestion } from 'interactive-quiz-kit';
+
+// Tạo một câu hỏi
+const myQuestion: TrueFalseQuestion = {
+  id: 'tf-001',
+  questionType: 'true_false',
+  prompt: 'Mặt trời mọc ở hướng Tây.',
+  correctAnswer: false,
+  points: 10
+};
+
+// Tạo một cấu hình quiz hoàn chỉnh
+const myQuizConfig: QuizConfig = {
+  id: 'my-first-headless-quiz',
+  title: 'Quiz Khoa Học Vui',
+  questions: [myQuestion],
+  settings: {
+    shuffleQuestions: true,
+    timeLimitMinutes: 10
+  }
+};
+```
+
+**Các kiểu dữ liệu quan trọng nhất:**
+*   `QuizConfig`: Toàn bộ cấu hình quiz.
+*   `QuizQuestion`: Union type của tất cả các loại câu hỏi.
+*   Các kiểu câu hỏi cụ thể: `MultipleChoiceQuestion`, `FillInTheBlanksQuestion`, `BlocklyProgrammingQuestion`, v.v.
+*   `QuizResult`: Cấu trúc dữ liệu kết quả trả về.
+
+---
+
+## III. Sử dụng Dịch vụ Lõi
+
+### 1. `QuizEditorService`: Tạo và Chỉnh sửa Quiz
+
+Service này cho phép bạn thực hiện các thao tác CRUD (Create, Read, Update, Delete) trên một đối tượng `QuizConfig`.
+
+```typescript
+import { QuizEditorService, emptyQuiz } from 'interactive-quiz-kit/services';
+import type { QuestionTypeStrings } from 'interactive-quiz-kit';
+
+// Bắt đầu với một quiz rỗng
+const editor = new QuizEditorService(emptyQuiz);
+
+// Tạo một template câu hỏi trắc nghiệm mới
+const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice');
+
+// Cập nhật thông tin cho câu hỏi
+mcqTemplate.prompt = "Hành tinh nào gần mặt trời nhất?";
+if (mcqTemplate.questionType === 'multiple_choice') {
+  mcqTemplate.options = [
+    { id: 'opt1', text: 'Trái Đất' },
+    { id: 'opt2', text: 'Sao Hỏa' },
+    { id: 'opt3', text: 'Sao Thủy' },
+  ];
+  mcqTemplate.correctAnswerId = 'opt3';
+}
+
+// Thêm câu hỏi vào quiz
+editor.addQuestion(mcqTemplate);
+
+// Xóa câu hỏi (nếu cần, ví dụ tại index 0)
+// editor.deleteQuestionByIndex(0);
+
+// Lấy đối tượng QuizConfig cuối cùng
+const finalQuizConfig = editor.getQuiz();
+
+console.log(JSON.stringify(finalQuizConfig, null, 2));
+```
+
+### 2. `QuizEngine`: Chạy một Phiên làm bài Quiz
+
+Service này là bộ não xử lý logic khi một người dùng đang làm bài quiz.
+
+```typescript
+import { QuizEngine } from 'interactive-quiz-kit/services';
+import type { QuizConfig, QuizResult } from 'interactive-quiz-kit';
+
+// Giả sử bạn đã có một đối tượng myQuizConfig
+const myQuizConfig: QuizConfig = /* ... */;
+
+console.log("Bắt đầu quiz...");
+
+const engine = new QuizEngine({
+  config: myQuizConfig,
+  callbacks: {
+    onQuestionChange: (question, qNum, total) => {
+      console.log(`\n--- Câu hỏi ${qNum}/${total} ---`);
+      console.log(question?.prompt);
+    },
+    onQuizFinish: (result: QuizResult) => {
+      console.log("\n--- KẾT QUẢ ---");
+      console.log(`Điểm số: ${result.score}/${result.maxScore}`);
+      console.log(`Phần trăm: ${result.percentage.toFixed(2)}%`);
+      console.log(`Trạng thái: ${result.passed ? 'Đạt' : 'Không đạt'}`);
+    }
+  }
+});
+
+// Mô phỏng quá trình làm bài
+const question1 = engine.getCurrentQuestion();
+if (question1) {
+  // Giả sử câu 1 là True/False
+  engine.submitAnswer(question1.id, false); 
+}
+
+engine.nextQuestion();
+
+const question2 = engine.getCurrentQuestion();
+if (question2) {
+    // Giả sử câu 2 là Multiple Choice
+  engine.submitAnswer(question2.id, 'id_cua_dap_an_dung');
+}
+
+// Kết thúc quiz
+engine.calculateResults();
+```
+
+---
+
+## IV. Tạo Nội dung bằng AI
+
+Bạn có thể sử dụng các flow AI để tự động tạo câu hỏi. Các hàm này là `async`.
+
+*Lưu ý: Để sử dụng, bạn cần có môi trường đã cấu hình Google Genkit và các biến môi trường cần thiết (ví dụ: `GOOGLE_API_KEY`).*
+
+```typescript
+import { generateMCQQuestion, generateQuizPlan } from 'interactive-quiz-kit/ai';
+
+async function createAIQuestion() {
+  try {
+    console.log('Đang tạo câu hỏi trắc nghiệm về Hệ Mặt Trời...');
+    const result = await generateMCQQuestion({
+      topic: 'Hệ Mặt Trời',
+      difficulty: 'easy'
+    });
+
+    if (result.question) {
+      console.log('Câu hỏi đã được tạo:');
+      console.log(JSON.stringify(result.question, null, 2));
+    } else {
+      console.log('AI không thể tạo câu hỏi.');
+    }
+
+  } catch (error) {
+    console.error('Lỗi khi tạo câu hỏi AI:', error);
+  }
+}
+
+// createAIQuestion();
+```
+
+---
+
+## V. Đóng gói và Xuất bản
+
+Các hàm này giúp tạo ra các thành phần của một gói SCORM. Chúng trả về nội dung dạng chuỗi (string) mà bạn có thể ghi ra file.
+
+```typescript
+import { generateSCORMManifest, generateLauncherHTML } from 'interactive-quiz-kit/services';
+import type { QuizConfig } from 'interactive-quiz-kit';
+// import * as fs from 'fs'; // Dùng trong môi trường Node.js
+
+// Giả sử bạn đã có một đối tượng myQuizConfig
+const myQuizConfig: QuizConfig = /* ... */;
+
+// Tạo nội dung manifest
+const manifestXML = generateSCORMManifest(myQuizConfig, "1.2");
+console.log('--- imsmanifest.xml ---');
+console.log(manifestXML);
+// fs.writeFileSync('dist/imsmanifest.xml', manifestXML);
+
+
+// Tạo nội dung file HTML launcher
+const launcherHTML = generateLauncherHTML(myQuizConfig);
+console.log('\n--- index.html ---');
+console.log(launcherHTML);
+// fs.writeFileSync('dist/index.html', launcherHTML);
+```
+
+**Lưu ý:** Hàm `exportQuizAsSCORMZip` được thiết kế để chạy trên trình duyệt vì nó tương tác với DOM để kích hoạt tải file. Nếu bạn muốn đóng gói ZIP ở phía backend, bạn cần sử dụng một thư viện như `jszip` và tự mình thực hiện các bước tương tự như trong file `services/scormPackaging.ts`.

package/README.md

@@ -1,176 +1,229 @@
-# Interactive Quiz Kit Library
-
-## Giới thiệu
-
-**Interactive Quiz Kit** là một thư viện JavaScript/TypeScript được xây dựng với React, được thiết kế để dễ dàng tạo, quản lý và chơi các bài quiz tương tác. Thư viện này cung cấp một bộ logic lõi mạnh mẽ (\`QuizEngine\`), các thành phần giao diện người dùng React có thể tái sử dụng, và hỗ trợ cho nhiều loại câu hỏi đa dạng. Nó được xây dựng với mục tiêu dễ dàng mở rộng và tích hợp vào các ứng dụng React hiện có.
-
-Các tính năng nổi bật bao gồm quản lý trạng thái quiz, chấm điểm tự động, tích hợp SCORM, gửi kết quả qua webhook, và các công cụ tạo quiz trực quan với sự hỗ trợ của AI (sử dụng Genkit và Gemini) để tạo câu hỏi đơn lẻ và toàn bộ bài quiz.
-
-## Tính năng cốt lõi
-
-### 1. \`QuizEngine\` (Logic Lõi)
-Thành phần trung tâm xử lý toàn bộ logic của quiz:
-- **Quản lý Câu hỏi:** Theo dõi câu hỏi hiện tại, điều hướng (tiến, lùi, nhảy đến câu bất kỳ), và phục hồi trạng thái.
-- **Xáo trộn:** Hỗ trợ xáo trộn thứ tự câu hỏi và các lựa chọn trong câu hỏi (nếu được cấu hình).
-- **Chấm điểm:** Tự động chấm điểm dựa trên câu trả lời của người dùng và đáp án đúng được định nghĩa cho từng loại câu hỏi.
-- **Tính toán Kết quả:** Tổng hợp điểm số, tính phần trăm, xác định trạng thái đậu/rớt.
-- **Phân tích Thời gian:** Theo dõi thời gian làm bài cho từng câu hỏi và tổng thời gian làm quiz.
-- **Tích hợp SCORM:** Làm việc với \`SCORMService\` để báo cáo điểm, trạng thái hoàn thành và thời gian cho LMS.
-- **Gửi Webhook:** Gửi kết quả quiz chi tiết đến một URL webhook được cấu hình.
-- **Callbacks:** Cung cấp các callback cho các sự kiện quan trọng (bắt đầu quiz, thay đổi câu hỏi, nộp bài, kết thúc quiz) để tùy chỉnh hành vi.
-
-### 2. Thành phần Giao diện Người dùng React
-Thư viện cung cấp các thành phần React sẵn sàng sử dụng:
-- **\`QuizPlayer\`:** Thành phần chính để hiển thị và tương tác với bài quiz.
-- **\`QuizResult\`:** Hiển thị kết quả chi tiết sau khi hoàn thành quiz.
-- **\`QuestionRenderer\`:** Tự động hiển thị câu hỏi dựa trên loại của nó.
-- **Giao diện cho từng Loại Câu hỏi:** Các thành phần UI chuyên biệt cho mỗi loại câu hỏi được hỗ trợ (ví dụ: \`MultipleChoiceQuestionUI\`, \`TrueFalseQuestionUI\`, \`ScratchProgrammingQuestionUI\` v.v.).
-- **\`QuizDataManagement\`:** Cho phép người dùng nhập quiz từ file JSON.
-
-### 3. Công cụ Tạo Quiz (\`QuizAuthoringTool\`)
-Một bộ thành phần mạnh mẽ để tạo và chỉnh sửa quiz một cách trực quan:
-- **Chỉnh sửa Cài đặt Quiz:** Tiêu đề, mô tả, các tùy chọn xáo trộn, giới hạn thời gian, v.v.
-- **Quản lý Câu hỏi:** Thêm, sửa, xóa, sắp xếp lại thứ tự câu hỏi.
-- **\`EditQuestionModal\`:** Một modal đa năng để chỉnh sửa chi tiết của từng câu hỏi, bao gồm cả metadata phong phú.
-- **Hỗ trợ Tạo bằng AI:**
-    - **\`AIQuestionGeneratorModal\`:** Tạo câu hỏi đơn lẻ bằng AI dựa trên chủ đề, ngữ cảnh, loại câu hỏi, và cấp độ Bloom.
-    - **\`AIFullQuizGeneratorModal\`:** Tạo toàn bộ bài quiz bằng AI theo quy trình hai giai đoạn (lập kế hoạch quiz và tạo câu hỏi chi tiết), cho phép người dùng xem xét và điều chỉnh kế hoạch.
-
-### 4. Các Loại Câu hỏi được Hỗ trợ
-Thư viện hỗ trợ một loạt các loại câu hỏi:
-1.  **Multiple Choice (Trắc nghiệm - một đáp án)**
-2.  **Multiple Response (Trắc nghiệm - nhiều đáp án)**
-3.  **Fill In The Blanks (Điền vào chỗ trống)**
-4.  **Drag and Drop (Kéo thả)** - Hiện UI Player dùng Select thay thế
-5.  **True/False (Đúng/Sai)**
-6.  **Short Answer (Trả lời ngắn)**
-7.  **Numeric (Trả lời bằng số)**
-8.  **Sequence (Sắp xếp thứ tự)**
-9.  **Matching (Ghép nối)** - Hiện UI Player dùng Select thay thế cho từng mục
-10. **Hotspot (Điểm nóng trên ảnh)**
-11. **Blockly Programming (Lập trình kéo thả khối Blockly)**
-12. **Scratch Programming (Lập trình Scratch - sử dụng Blockly với renderer Zelos)**
-
-### 5. Quản lý Dữ liệu Quiz
-- **Định nghĩa Kiểu TypeScript:** Cung cấp các interface rõ ràng (\`QuizConfig\`, \`QuizQuestion\`, v.v.) cho cấu trúc dữ liệu quiz.
-- **Nhập/Xuất JSON:** Dễ dàng lưu và tải quiz dưới dạng file JSON.
-- **Đóng gói SCORM:**
-    - \`SCORMManifestGenerator\`: Tạo file \`imsmanifest.xml\`.
-    - \`HTMLLauncherGenerator\`: Tạo file HTML launcher cho SCORM.
-
-### 6. Tích hợp AI (với Genkit & Gemini)
-- Sử dụng các flow Genkit để tương tác với Gemini API.
-- **Tạo Câu hỏi Đơn lẻ:** Các flow như \`generateMCQQuestion\`, \`generateTrueFalseQuestion\`, v.v.
-- **Tạo Toàn bộ Quiz:**
-    - \`generate-quiz-plan-flow.ts\`: Lập kế hoạch cấu trúc quiz.
-    - \`generateQuestionsFromQuizPlanFlow.ts\`: Tạo các câu hỏi chi tiết dựa trên kế hoạch.
-
-## Thành phần và Dịch vụ Chính
-
-- **\`QuizPlayer.tsx\`**: Thành phần chính để người dùng làm quiz.
-- **\`QuizAuthoringTool.tsx\`**: Giao diện chính để tạo và chỉnh sửa quiz.
-- **\`QuizEngine.ts\`**: Lớp logic xử lý trạng thái, chấm điểm, và các hoạt động của quiz.
-- **\`SCORMService.ts\`**: Xử lý giao tiếp với SCORM API của LMS.
-- **\`QuestionRenderer.tsx\`**: Quyết định và hiển thị UI phù hợp cho từng loại câu hỏi.
-- **Các thành phần UI câu hỏi (ví dụ: \`MultipleChoiceQuestionUI.tsx\`)**: Hiển thị và xử lý tương tác cho từng loại câu hỏi cụ thể.
-- **Các form câu hỏi (ví dụ: \`MultipleChoiceQuestionForm.tsx\`)**: Được sử dụng trong \`EditQuestionModal\` để chỉnh sửa từng loại câu hỏi.
-- **Các flow AI (trong \`src/ai/flows/\`)**: Logic Genkit để tạo nội dung quiz bằng AI.
-
-## Cài đặt (Hướng dẫn nếu tách thành thư viện riêng)
-
-Nếu thư viện này được publish lên npm, bạn có thể cài đặt bằng:
-\`\`\`bash
-npm install interactive-quiz-kit
-# hoặc
-yarn add interactive-quiz-kit
-\`\`\`
-Để phát triển local và sử dụng trong project khác, bạn có thể dùng \`npm link\`.
-
-## Sử dụng Cơ bản (trong một ứng dụng React)
-
-### Hiển thị Quiz cho Người dùng:
-\`\`\`tsx
+# Interactive Quiz Kit
+
+[![NPM version](https://img.shields.io/npm/v/@thanh01pmt/interactive-quiz-kit.svg)](https://www.npmjs.com/package/@thanh01pmt/interactive-quiz-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Interactive Quiz Kit** is a comprehensive TypeScript library built with React, designed to effortlessly create, manage, play, and distribute interactive quizzes. It provides a robust core logic (`QuizEngine`), reusable React UI components, and support for a wide variety of question types.
+
+The library is architected for easy extension and integration, featuring a powerful authoring tool, AI-powered content generation (using Google's Genkit and Gemini), and SCORM packaging for seamless LMS integration.
+
+## ✨ Features
+
+*   **Robust Core Engine**: Handles state management, navigation, automatic grading, and time tracking.
+*   **Rich Question Support**: Includes 12+ question types, from Multiple Choice to complex ones like Blockly/Scratch Programming and Hotspot.
+*   **React-based UI Kit**: A full suite of components to build quiz players and authoring tools.
+    *   `<QuizPlayer>`: The main component for taking quizzes.
+    *   `<QuizAuthoringTool>`: A powerful interface for creating and editing quizzes.
+*   **Headless Mode**: Use all core logic, services, and AI flows independently of the React UI. Ideal for backend integrations, custom frontends, or automation scripts.
+*   **AI-Powered Generation**:
+    *   Generate individual questions based on topic, context, and difficulty.
+    *   Generate entire, well-structured quizzes using a two-stage planning and generation process.
+*   **SCORM & Webhook Integration**:
+    *   Package quizzes as SCORM 1.2 or 2004 compliant ZIP files.
+    *   Send detailed quiz results to a specified webhook URL.
+
+## 🚀 Installation
+
+```bash
+npm install @thanh01pmt/interactive-quiz-kit
+# or
+yarn add @thanh01pmt/interactive-quiz-kit
+```
+
+**Peer Dependencies:** This library requires `react` and `react-dom` as peer dependencies. Ensure they are installed in your project.
+
+## 📚 Usage
+
+This library supports two primary modes of usage: with the built-in React UI, or in a "headless" mode using only the core logic.
+
+### 1. Standard Mode (with React UI)
+
+This is the quickest way to get a fully functional quiz application up and running.
+
+#### Example: Displaying a Quiz with `<QuizPlayer>`
+
+```tsx
 import React, { useState } from 'react';
-import { QuizPlayer, QuizConfig, QuizResult as QuizResultType } from 'interactive-quiz-kit';
+import { QuizPlayer } from '@thanh01pmt/interactive-quiz-kit/react-ui';
+import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
 
-// Ví dụ cấu hình quiz (hoặc tải từ JSON)
+// 1. Define or load your quiz configuration
 const myQuiz: QuizConfig = {
-  id: "my-example-quiz",
-  title: "My Example Quiz",
-  questions: [ /* ... mảng các đối tượng câu hỏi ... */ ],
-  settings: { /* ... cài đặt quiz ... */ }
+  id: "my-first-quiz",
+  title: "React Basics Quiz",
+  questions: [ /* ... array of question objects ... */ ],
+  settings: {
+    shuffleQuestions: true,
+    timeLimitMinutes: 15
+  }
 };
 
-const App = () => {
-  const [quizResult, setQuizResult] = useState<QuizResultType | null>(null);
-
-  const handleQuizComplete = (result: QuizResultType) => {
+const MyQuizPage = () => {
+  const handleQuizComplete = (result: QuizResult) => {
     console.log("Quiz Complete!", result);
-    setQuizResult(result);
-    // Xử lý kết quả (ví dụ: hiển thị, gửi lên server)
-  };
-
-  const handleExitQuiz = () => {
-    console.log("Exiting quiz");
-    // Điều hướng người dùng hoặc làm mới trạng thái
+    // Send result to your backend, or display a summary
   };
 
   return (
-    <QuizPlayer
-      quizConfig={myQuiz}
-      onQuizComplete={handleQuizComplete}
-      onExitQuiz={handleExitQuiz} // Tùy chọn
-    />
+    <div className="container">
+      <QuizPlayer
+        quizConfig={myQuiz}
+        onQuizComplete={handleQuizComplete}
+      />
+    </div>
   );
 };
+```
 
-export default App;
-\`\`\`
+#### Example: Using the `<QuizAuthoringTool>`
 
-### Sử dụng Công cụ Tạo Quiz:
-\`\`\`tsx
-import React, { useState } from 'react';
-import { QuizAuthoringTool, QuizConfig, emptyQuiz } from 'interactive-quiz-kit';
+Embed the complete authoring experience to allow users to create and edit quizzes.
 
-const AuthoringPage = () => {
-  // initialQuiz có thể là null (tạo mới), hoặc một QuizConfig đã có để sửa
-  const [initialQuiz, setInitialQuiz] = useState<QuizConfig | null>(null); 
+```tsx
+import React from 'react';
+import { QuizAuthoringTool, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit/react-ui';
+import type { QuizConfig } from '@thanh01pmt/interactive-quiz-kit';
 
-  const handleSaveAuthoredQuiz = (savedQuiz: QuizConfig) => {
-    console.log("Quiz Saved:", savedQuiz);
-    // Lưu quiz (ví dụ: localStorage, backend)
+const MyAuthoringPage = () => {
+  const handleSave = (quiz: QuizConfig) => {
+    console.log("Quiz saved:", quiz);
+    // Persist the quiz config (e.g., to a database or localStorage)
   };
 
-  const handleExitAuthoring = () => {
-    console.log("Exiting authoring tool");
-    // Điều hướng người dùng
-  };
-  
+  // Start with an empty quiz template for creation
   return (
     <QuizAuthoringTool
-      initialQuizConfig={initialQuiz || emptyQuiz} // Cung cấp quiz rỗng nếu tạo mới
-      onSaveQuiz={handleSaveAuthoredQuiz}
-      onExitAuthoring={handleExitAuthoring} // Tùy chọn
+      initialQuizConfig={emptyQuiz}
+      onSaveQuiz={handleSave}
     />
   );
 };
+```
+
+### 2. Headless Mode (Core Logic Only)
+
+Use the library's services, types, and AI flows in any JavaScript/TypeScript environment (e.g., Node.js backend, other frontend frameworks, scripts).
+
+> For detailed examples and a full component list, see [**HEADLESS.md**](./HEADLESS.md).
+
+#### Example: Creating a Quiz Programmatically with `QuizEditorService`
+
+This service allows you to safely manipulate a `QuizConfig` object.
+
+```typescript
+import { QuizEditorService, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit';
+import type { MultipleChoiceQuestion } from '@thanh01pmt/interactive-quiz-kit';
+
+// Start with an empty quiz config
+const editor = new QuizEditorService(emptyQuiz);
+
+// Create a question template
+const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice') as MultipleChoiceQuestion;
+
+// Populate the question details
+mcqTemplate.prompt = "What is the capital of France?";
+mcqTemplate.options = [
+  { id: 'opt1', text: 'Berlin' },
+  { id: 'opt2', text: 'Paris' },
+  { id: 'opt3', text: 'Madrid' },
+];
+mcqTemplate.correctAnswerId = 'opt2';
+
+// Add the question to the quiz
+editor.addQuestion(mcqTemplate);
+
+// Get the final, updated quiz configuration
+const finalQuizConfig = editor.getQuiz();
+
+// Now you can save `finalQuizConfig` to your database
+console.log(finalQuizConfig);
+```
+
+#### Example: Running a Quiz Session with `QuizEngine`
+
+This is useful for backend-driven quizzes or for running simulations.
+
+```typescript
+import { QuizEngine } from '@thanh01pmt/interactive-quiz-kit';
+import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
+
+const myQuizConfig: QuizConfig = /* ... load your quiz config ... */;
+
+const engine = new QuizEngine({
+  config: myQuizConfig,
+  callbacks: {
+    onQuizFinish: (result: QuizResult) => {
+      console.log(`Quiz finished! Final score: ${result.score}`);
+    }
+  }
+});
+
+// Simulate answering the first question
+const firstQuestion = engine.getCurrentQuestion();
+if (firstQuestion) {
+  engine.submitAnswer(firstQuestion.id, 'id_of_the_user_answer');
+}
+
+// Finalize the quiz
+engine.calculateResults();
+```
+
+#### Example: Generating a Question with AI
+
+Leverage Google Gemini to create quiz content on the fly. *Requires Genkit environment setup.*
+
+```typescript
+import { generateTrueFalseQuestion } from '@thanh01pmt/interactive-quiz-kit/ai';
+
+async function createNewQuestion() {
+  try {
+    const { question } = await generateTrueFalseQuestion({
+      topic: "The history of the internet",
+      difficulty: "medium"
+    });
+
+    if (question) {
+      console.log("AI-generated question:", question);
+      // Save to your database
+    }
+  } catch (error) {
+    console.error("Failed to generate question:", error);
+  }
+}
+```
+
+## Supported Question Types
 
-export default AuthoringPage;
-\`\`\`
-
-## Cấu trúc Dữ liệu
-- **\`QuizConfig\`**: Interface chính định nghĩa toàn bộ cấu trúc của một bài quiz, bao gồm ID, tiêu đề, mô tả, danh sách câu hỏi (\`QuizQuestion[]\`), và các cài đặt (\`QuizSettings\`).
-- **\`QuizQuestion\`**: Một union type bao gồm tất cả các loại câu hỏi cụ thể (ví dụ: \`MultipleChoiceQuestion\`, \`TrueFalseQuestion\`). Mỗi loại câu hỏi kế thừa từ \`BaseQuestion\` và có các thuộc tính riêng.
-- **JSON Schemas**: Các schema JSON cho \`QuizConfig\` và từng loại câu hỏi được cung cấp trong thư vực \`schemas/\` để tham khảo và xác thực.
-
-## Đóng góp
-Mọi đóng góp đều được chào đón! Vui lòng gửi pull request hoặc mở issue nếu bạn có ý tưởng cải thiện hoặc tìm thấy lỗi.
-
-## Giấy phép
-MIT
-        
-## Các Vấn đề đã Biết (Known Issues - Library Specific)
-*   **Tích hợp Blockly/Scratch:** Cần đảm bảo các tài nguyên Blockly (CSS, media) được tải đúng cách khi thư viện được sử dụng độc lập. \`ScratchProgrammingQuestionUI\` hiện sử dụng renderer 'zelos' của Blockly để có giao diện giống Scratch.
-*   **Đóng gói SCORM:** Các hàm tạo manifest và launcher có sẵn, nhưng việc đóng gói tự động thành file ZIP hoàn chỉnh cần được người dùng thực hiện thủ công hoặc tích hợp thêm.
-*   **Tạo Câu hỏi AI cho Drag & Drop và Hotspot:** Các flow AI chuyên biệt để tạo câu hỏi Drag & Drop và Hotspot từ đầu chưa được triển khai. AI cũng chưa hỗ trợ tạo ảnh cho câu hỏi Hotspot.
-*   **Hoàn thiện UI cho Scratch Programming:** Giao diện người dùng (\`ScratchProgrammingQuestionUI.tsx\`) và form tương ứng trong công cụ tạo quiz (\`ScratchProgrammingQuestionForm.tsx\`) đã được tạo nhưng có thể cần tinh chỉnh thêm về mặt thẩm mỹ và toolbox mặc định để hoàn toàn giống với môi trường Scratch tiêu chuẩn.
+The library supports a wide array of 12+ question types, including:
+- `multiple_choice`
+- `multiple_response`
+- `true_false`
+- `short_answer`
+- `numeric`
+- `fill_in_the_blanks`
+- `sequence`
+- `matching`
+- `drag_and_drop`
+- `hotspot`
+- `blockly_programming`
+- `scratch_programming`
+
+## Known Issues
+
+*   **Blockly/Scratch Integration**: Requires manual copying of assets (`js`, `css`, `media`) from the `blockly` or `scratch-blocks` packages into your project's `public` folder for the UI components to render correctly.
+*   **SCORM Packaging**: The `exportQuizAsSCORMZip` function generates a nearly complete package. However, you **must manually** add the library's JavaScript bundle and any necessary CSS (like for Blockly) to the ZIP archive for it to function in an LMS.
+*   **AI Generation Limits**: AI generation is not yet supported for `Drag and Drop`, `Hotspot`, `Blockly`, or `Scratch` question types due to their complexity.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue if you have ideas for improvements or find a bug.
+
+1.  Fork the repository.
+2.  Create your feature branch (`git checkout -b feature/AmazingFeature`).
+3.  Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).
+4.  Push to the branch (`git push origin feature/AmazingFeature`).
+5.  Open a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thanh01.pmt/interactive-quiz-kit",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A comprehensive library for creating, managing, and playing interactive quizzes, with AI generation and SCORM support.",
   "keywords": [
     "react",