broker-core-sdk 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# Core SDK - Adaptive Learning System
+
+Đây là bộ công cụ lõi (Core SDK) chứa toàn bộ logic nghiệp vụ, thuật toán học tập, hằng số (constants) và các định nghĩa dữ liệu (types) dùng chung cho toàn bộ hệ thống Adaptive Learning. SDK này được thiết kế theo hướng **Functional Programming**, hỗ trợ **Tree-shaking** tối đa và đảm bảo tính nhất quán (Type-safety) giữa các nền tảng Web (Admin), Mobile (Learner) và Backend.
+
+---
+
+## 🚀 Tính năng chính
+
+- **Constants Management**: Quản lý các biến hằng (như loại phần tử, mức độ tự tin) tập trung.
+- **Learning Engine**: Thuật toán Spaced Repetition (Lặp lại ngắt quãng) và tính toán mức độ thành thạo (Mastery).
+- **Game Engine**: Logic "trọng tài" kiểm tra kết quả Đúng/Sai thống nhất cho tất cả các dạng Game (Quiz, Sorting, Matching, Hotspot, Memory Card).
+- **Slide Renderer Math**: Bộ công thức chuyển đổi tọa độ linh hoạt giữa giá trị `%` và `Pixel`.
+- **Discriminated Union Types**: Hệ thống Type chặt chẽ, tự động ánh xạ cấu trúc `data` theo `type` của phần tử, hỗ trợ Autocomplete tối đa cho IDE.
+
+---
+
+## 📦 Cài đặt
+
+### Dành cho dự án trong cùng Monorepo (Workspace)
+Thêm vào file `package.json` của project cần dùng:
+```json
+"dependencies": {
+  "@broker/core-sdk": "workspace:*"
+}
+```
+
+### Dành cho dự án độc lập
+```bash
+npm install ../path-to/core-sdk
+```
+
+---
+
+## 🛠 Hướng dẫn sử dụng chi tiết
+
+### 1. Hệ thống Constants & Type
+Bộ SDK cung cấp sẵn các object constants giúp bạn không phải fix cứng chuỗi (`"QUIZ"`, `"High"`,...) ở các dự án khác.
+
+```typescript
+import { ELEMENT_TYPES, CONFIDENCE_LEVELS } from "@broker/core-sdk";
+import type { ElementType, ConfidenceLevel } from "@broker/core-sdk";
+
+// Sử dụng thay cho hardcode text
+const myType: ElementType = ELEMENT_TYPES.QUIZ;
+const conf: ConfidenceLevel = CONFIDENCE_LEVELS.HIGH;
+```
+
+### 2. SlideElement & Type Safety (Mới)
+`SlideElement` hiện đã được chuyển sang dạng **Discriminated Union**. Khi bạn sử dụng trong code, IDE sẽ tự động gợi ý các trường trong `data` dựa trên `type`.
+
+```typescript
+import type { SlideElement } from "@broker/core-sdk";
+
+const element: SlideElement = {
+  id: "e1",
+  type: "QUIZ", // Khi type là QUIZ
+  position: { x: 0, y: 0, w: 100, h: 100 },
+  data: {
+    question: "TypeScript là gì?",
+    options: [{ id: "1", content: "Ngôn ngữ lập trình" }],
+    correctId: "1"
+  } // IDE sẽ autocomplete các trường của MultipleChoiceData
+};
+```
+
+### 3. Learning Engine (Tính toán lộ trình học)
+```typescript
+import { learningEngine, CONFIDENCE_LEVELS } from "@broker/core-sdk";
+
+const daysToAdd = learningEngine.calculateNextReview(true, CONFIDENCE_LEVELS.HIGH); // Kết quả: 7
+const isMastered = learningEngine.checkMastery(3, CONFIDENCE_LEVELS.HIGH); // Kết quả: true
+```
+
+---
+
+## 🏗 Cấu trúc SDK (Hệ thống Types mới)
+
+Thư mục `src/types/` đã được quy hoạch lại để dễ quản lý:
+
+- **`common.ts`**: Chứa các kiểu dữ liệu dùng chung cơ bản (như `Position`).
+- **`data.ts`**: Tập trung toàn bộ Payload của phần tử (`TextData`, `VideoData`, `MultipleChoiceData`,... và `ElementDataMap`).
+- **`elements.ts`**: Định nghĩa cấu trúc khung của phần tử (`SlideElement`, `ElementStyle`, `ElementType`).
+- **`models.ts`**: Các thực thể lớn của hệ thống (`Slide`, `UserProgress`, `ActionLog`).
+
+---
+
+## 🧪 Phát triển và Kiểm thử
+
+SDK là "trái tim" của hệ thống nên mọi thay đổi nhỏ đều có thể ảnh hưởng diện rộng.
+
+1. **Test Driven**:
+   ```bash
+   npm test
+   ```
+
+2. **Build & Verify Types**:
+   ```bash
+   npm run build
+   ```
+   (Lệnh này sử dụng `tsup` để đóng gói và tạo file `.d.ts`. Luôn chạy lệnh này để đảm bảo không có lỗi Type trước khi commit).
+
+---
+
+## 📝 Quy định khi mở rộng (Guidelines)
+
+- **Không Magic Strings**: Luôn định nghĩa hằng số vào `elements.ts` (cho ELEMENT_TYPES) hoặc `models.ts` (cho CONFIDENCE_LEVELS).
+- **Consolidate Data**: Khi thêm loại phần tử mới, hãy định nghĩa Interface data của nó trong `data.ts` và cập nhật vào `ElementDataMap`.
+- **Discriminated Union**: Không sử dụng `any` cho trường `data` trong `SlideElement`. Hãy để hệ thống tự ánh xạ thông qua `ElementDataMap`.
+- **Vanilla TS**: SDK không được phụ thuộc vào bất kỳ Framework nào (React/Node-specific).
+
+---
+
+_© 2026 Broker Adaptive Learning Team - Tài liệu nội bộ._

package/docs/codebase/.codebase-scan.txt

@@ -0,0 +1,230 @@
+
+=== DIRECTORY TREE (max depth 3, source files only) ===
+.gitignore
+docs
+docs\codebase
+docs\codebase\.codebase-scan.txt
+package-lock.json
+package.json
+README.md
+src
+src\data
+src\engines
+src\engines\game-engine.ts
+src\engines\learning-engine.ts
+src\index.ts
+src\renderer
+src\renderer\slide-renderer.ts
+src\sync
+src\sync\action-manager.ts
+src\types
+src\types\actions.ts
+src\types\common.ts
+src\types\data.ts
+src\types\elements.ts
+src\types\index.ts
+src\types\models.ts
+tests
+tests\game-engine.test.ts
+tests\learning-engine.test.ts
+tests\slide-renderer.test.ts
+tsconfig.json
+
+=== STACK DETECTION (manifest files) ===
+
+--- package-lock.json ---
+{
+  "name": "@broker/core-sdk",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@broker/core-sdk",
+      "version": "1.0.0",
+      "license": "ISC",
+      "devDependencies": {
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.5"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+      "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+
+[TRUNCATED] Showing first 80 of 2601 lines.
+--- package.json ---
+{
+  "name": "@broker/core-sdk",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  }
+}
+
+
+=== ENTRY POINTS ===
+Found: src/index.ts
+
+=== LINTING AND FORMATTING CONFIG ===
+Found: tsconfig.json
+
+=== ENVIRONMENT VARIABLE TEMPLATES ===
+No .env.example or .env.template found. Identify required environment variables by searching the code and config for environment variable reads.
+
+=== TODO / FIXME / HACK (production code only, test dirs excluded) ===
+None found.
+
+=== GIT RECENT COMMITS (last 20) ===
+b929636 feat: export core engines, renderers, and types from index entry point
+691b6a2 feat: define interface structures and type maps for core element data types
+dcc6a31 feat: implement game result validation engine and core element type definitions
+e8689e3 docs: update installation and configuration instructions in README
+23345b5 feat: implement core types, models, and learning engine structure with scope renaming to @broker/core-sdk
+b500b5a docs: update installation instructions and usage examples in README.md
+9eefc2b feat: add Slide, SlideElement, and ElementStyle type definitions
+2cc0159 feat: define Slide and UserProgress types for core SDK models
+602b2a4 feat: implement game engine validation logic and define core base and action logging types
+267d21e feat: initialize core-sdk with game engine, slide renderer, and common data models
+
+=== HIGH-CHURN FILES (last 90 days, top 20) ===
+   4 README.md
+   4 src/types/slide-element.ts
+   3 src/engines/game-engine.ts
+   3 src/types/index.ts
+   3 src/engines/learning-engine.ts
+   3 src/types/action-log.ts
+   3 src/types/base.ts
+   3 src/types/user-progress.ts
+   2 src/index.ts
+   2 src/types/data.ts
+   2 src/types/elements.ts
+   2 package-lock.json
+   2 package.json
+   1 src/types/actions.ts
+   1 src/types/common.ts
+   1 src/types/models.ts
+   1 .gitignore
+   1 src/renderer/slide-renderer.ts
+   1 src/sync/action-manager.ts
+   1 src/types/game-logic.ts
+
+=== MONOREPO SIGNALS ===
+No monorepo signals detected.
+
+=== CODE METRICS ===
+Total files scanned: 19
+Total lines of code: 3261
+
+Files by language:
+  TypeScript: 14
+  Other: 5
+
+Top 10 largest files:
+package-lock.json: 83.2KB
+README.md: 4.7KB
+tests\game-engine.test.ts: 3.2KB
+src\types\actions.ts: 3.1KB
+src\types\elements.ts: 1.9KB
+src\types\data.ts: 1.6KB
+src\engines\game-engine.ts: 1.5KB
+tsconfig.json: 1.1KB
+tests\learning-engine.test.ts: 1.1KB
+src\engines\learning-engine.ts: 1.0KB
+
+=== CI/CD PIPELINES ===
+No CI/CD pipelines detected.
+
+=== CONTAINERS & ORCHESTRATION ===
+No containerization configs detected.
+
+=== SECURITY & COMPLIANCE ===
+No security configs detected.
+
+=== PERFORMANCE & TESTING ===
+No performance testing configs detected.
+
+=== SCAN COMPLETE ===

package/docs/codebase/ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# Architecture
+
+## Core Sections (Required)
+
+### 1) Architectural Style
+
+- Primary style: Library / SDK (Functional Programming)
+- Why this classification: Stated in `README.md` that it is designed with Functional Programming and Tree-shaking.
+- Primary constraints: Must be framework agnostic (Vanilla TS), no Magic Strings, must use strict Discriminated Union types.
+
+### 2) System Flow
+
+```text
+[Consumer App] -> [Core SDK Export (src/index.ts)] -> [Pure Function Engine (e.g. game-engine.ts)] -> [Result]
+```
+
+### 3) Layer/Module Responsibilities
+
+| Layer or module | Owns | Must not own | Evidence |
+|-----------------|------|--------------|----------|
+| `src/engines` | Algorithmic logic (Spaced Repetition, Game Checks) | State management, UI | `README.md` |
+| `src/types` | Data definitions and Constants | Implementations | `README.md` |
+
+### 4) Reused Patterns
+
+| Pattern | Where found | Why it exists |
+|---------|-------------|---------------|
+| Discriminated Union | `src/types/elements.ts` (`SlideElement`) | To map structures automatically and ensure Type-safety across the ecosystem. |
+
+### 5) Known Architectural Risks
+
+- [TODO] Expanding types might require significant refactoring across the `ElementDataMap`.
+
+### 6) Evidence
+
+- `README.md`
+- `src/index.ts`

package/docs/codebase/CONCERNS.md

@@ -0,0 +1,19 @@
+# Concerns and Technical Debt
+
+## Core Sections (Required)
+
+### 1) Technical Debt & TODOs
+
+- NONE detected in code comments.
+
+### 2) High-Churn Areas
+
+- `README.md` (4 commits)
+- `src/types/slide-element.ts` (4 commits) - Indicates high activity around the core element types.
+- `src/engines/game-engine.ts` (3 commits)
+- `src/engines/learning-engine.ts` (3 commits)
+- `src/types/index.ts` (3 commits)
+
+### 3) Evidence
+
+- Scan output

package/docs/codebase/CONVENTIONS.md

@@ -0,0 +1,22 @@
+# Coding Standards and Conventions
+
+## Core Sections (Required)
+
+### 1) Naming Conventions
+
+- Files: kebab-case (e.g., `slide-renderer.ts`, `learning-engine.ts`)
+- Variables/Functions: camelCase
+- Constants: UPPER_SNAKE_CASE (e.g., `ELEMENT_TYPES`, `CONFIDENCE_LEVELS`)
+- Types/Interfaces: PascalCase
+
+### 2) Coding Rules
+
+- **No Magic Strings**: Always define constants in `src/types/elements.ts` or `src/types/models.ts`. (from `README.md`)
+- **Consolidate Data**: When adding new element types, define the data interface in `data.ts` and add to `ElementDataMap`. (from `README.md`)
+- **Strict Discriminated Unions**: Do not use `any` for the `data` field in `SlideElement`. (from `README.md`)
+- **Framework Agnostic**: Code must be Vanilla TS without React/Node-specific dependencies. (from `README.md`)
+
+### 3) Evidence
+
+- `README.md`
+- Scan output

package/docs/codebase/INTEGRATIONS.md

@@ -0,0 +1,12 @@
+# Integrations
+
+## Core Sections (Required)
+
+### 1) External Services
+
+- External APIs: NONE (It is a local SDK)
+- Databases: NONE
+
+### 2) Evidence
+
+- `package.json` (no dependencies)

package/docs/codebase/STACK.md

@@ -0,0 +1,47 @@
+# Technology Stack
+
+## Core Sections (Required)
+
+### 1) Runtime Summary
+
+| Area | Value | Evidence |
+|------|-------|----------|
+| Primary language | TypeScript | `package.json`, `tsconfig.json` |
+| Runtime + version | Node.js / Browser (Library) | `package.json` |
+| Package manager | npm | `package-lock.json` |
+| Module/build system | tsup | `package.json` (`scripts.build`) |
+
+### 2) Production Frameworks and Dependencies
+
+List only high-impact production dependencies (frameworks, data, transport, auth).
+
+| Dependency | Version | Role in system | Evidence |
+|------------|---------|----------------|----------|
+| None | N/A | Zero-dependency SDK | `package.json` (no `dependencies`) |
+
+### 3) Development Toolchain
+
+| Tool | Purpose | Evidence |
+|------|---------|----------|
+| `typescript` | Type checking | `package.json` |
+| `tsup` | Module bundler (CJS/ESM) | `package.json` |
+| `vitest` | Unit testing | `package.json` |
+
+### 4) Key Commands
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### 5) Environment and Config
+
+- Config sources: `tsconfig.json`
+- Required env vars: None detected.
+- Deployment/runtime constraints: Deployed as an npm package via workspace or separate install, exports ESM and CommonJS. Framework-agnostic.
+
+### 6) Evidence
+
+- `package.json`
+- `tsconfig.json`

package/docs/codebase/STRUCTURE.md

@@ -0,0 +1,41 @@
+# Codebase Structure
+
+## Core Sections (Required)
+
+### 1) Top-Level Map
+
+List only meaningful top-level directories and files.
+
+| Path | Purpose | Evidence |
+|------|---------|----------|
+| `src/` | Source code root | Scan output |
+| `src/types/` | Data definitions, Discriminated Unions, and models | `README.md`, Scan output |
+| `src/engines/` | Core logic for game evaluation and spaced repetition | `README.md`, Scan output |
+| `src/renderer/` | Slide rendering and calculation math | `README.md`, Scan output |
+| `src/sync/` | Action manager handling | Scan output |
+| `tests/` | Unit test files | Scan output |
+
+### 2) Entry Points
+
+- Main runtime entry: `src/index.ts`
+- Secondary entry points (worker/cli/jobs): NONE
+- How entry is selected (script/config): Configured in `package.json` (`main`, `module`, `types`, `exports` fields).
+
+### 3) Module Boundaries
+
+| Boundary | What belongs here | What must not be here |
+|----------|-------------------|------------------------|
+| `src/types/` | Interfaces, types, and constants | Business logic, algorithms |
+| `src/engines/` | Pure functions for logic (Game Engine, Learning Engine) | UI rendering code, specific framework APIs |
+
+### 4) Naming and Organization Rules
+
+- File naming pattern: kebab-case (e.g., `game-engine.ts`, `slide-renderer.ts`)
+- Directory organization pattern: domain-based (`engines`, `types`, `renderer`)
+- Import aliasing or path conventions: Relative imports within the SDK, exported centrally via `src/index.ts`.
+
+### 5) Evidence
+
+- `docs/codebase/.codebase-scan.txt`
+- `package.json`
+- `README.md`

package/docs/codebase/TESTING.md

@@ -0,0 +1,22 @@
+# Testing
+
+## Core Sections (Required)
+
+### 1) Testing Frameworks
+
+- Test Runner: `vitest`
+
+### 2) Test Organization
+
+- Location: Tests are colocated in the `tests/` directory at the project root (e.g., `tests/game-engine.test.ts`).
+
+### 3) Key Commands
+
+```bash
+npm test
+```
+
+### 4) Evidence
+
+- `package.json`
+- Scan output

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "broker-core-sdk",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  }
+}

package/src/engines/game-engine.ts

@@ -0,0 +1,44 @@
+import type { GameDataMap } from "../types/data.js";
+import { GAME_TYPES, type GameType } from "../types/elements.js";
+
+/**
+ * Validator nhận vào toàn bộ object cấu hình (GameDataMap[T]).
+ */
+export const validateGameResult = <T extends GameType>(
+  type: T,
+  userAnswer: any,
+  correctData: GameDataMap[T], // Nhận cả object data thay vì chỉ string
+): boolean => {
+  switch (type) {
+    case GAME_TYPES.QUIZ: {
+      // Ép kiểu về MultipleChoiceData để truy cập correctId
+      const data = correctData as GameDataMap[typeof GAME_TYPES.QUIZ];
+      return userAnswer === data.correctId;
+    }
+
+    case GAME_TYPES.SORTING: {
+      const data = correctData as GameDataMap[typeof GAME_TYPES.SORTING];
+      return JSON.stringify(userAnswer) === JSON.stringify(data.correctOrder);
+    }
+
+    case GAME_TYPES.MATCHING: {
+      const data = correctData as GameDataMap[typeof GAME_TYPES.MATCHING];
+      const userSorted = [...userAnswer].sort();
+      const correctSorted = [...data.correctPairs].sort();
+      return JSON.stringify(userSorted) === JSON.stringify(correctSorted);
+    }
+
+    case GAME_TYPES.HOTSPOT: {
+      const data = correctData as GameDataMap[typeof GAME_TYPES.HOTSPOT];
+      const { x, y } = userAnswer;
+      const zone = data.zones.find((z) => z.id === data.correctZoneId);
+      if (!zone) return false;
+      return (
+        x >= zone.xMin && x <= zone.xMax && y >= zone.yMin && y <= zone.yMax
+      );
+    }
+
+    default:
+      return false;
+  }
+};

package/src/engines/learning-engine.ts

@@ -0,0 +1,35 @@
+import { CONFIDENCE_LEVELS } from "../types/models.js";
+import type { ConfidenceLevel } from "../types/models.js";
+
+/**
+ * Tính toán ngày review tiếp theo dựa trên kết quả và độ tự tin.
+ * - Đúng + Tự tin Cao: 7 ngày.
+ * - Đúng + Tự tin Vừa/Thấp: 1 ngày.
+ * - Sai: 0 ngày (ôn lại ngay).
+ */
+export const calculateNextReview = (
+  isCorrect: boolean,
+  confidence: ConfidenceLevel,
+): number => {
+  if (!isCorrect) {
+    return 0; // Ôn lại ngay lập tức
+  }
+
+  if (confidence === CONFIDENCE_LEVELS.HIGH) {
+    return 7; // Giãn cách 7 ngày cho câu trả lời tự tin
+  }
+
+  // Trường hợp Medium hoặc Low: Chỉ giãn cách 1 ngày
+  return 1;
+};
+
+/**
+ * Điều kiện Mastery (Thành thạo):
+ * Chuỗi đúng (streak) >= 3 và lần trả lời gần nhất có độ tự tin Cao.
+ */
+export const checkMastery = (
+  streak: number,
+  lastConfidence: ConfidenceLevel,
+): boolean => {
+  return streak >= 3 && lastConfidence === CONFIDENCE_LEVELS.HIGH;
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+import * as SlideRenderer from "./renderer/slide-renderer.js";
+import * as learningEngine from "./engines/learning-engine.js";
+import * as gameEngine from "./engines/game-engine.js";
+export * from "./types/index.js";
+export { SlideRenderer, learningEngine, gameEngine };

package/src/renderer/slide-renderer.ts

@@ -0,0 +1,27 @@
+/**
+ * Chuyển đổi tọa độ từ Pixel sang % (Dùng cho Admin Builder)
+ * Canvas Builder & Percentage Positioning
+ */
+export const calculatePercentPosition = (
+  pixelPos: { left: number; top: number; width: number; height: number },
+  canvasSize: { width: number; height: number },
+) => ({
+  x: (pixelPos.left / canvasSize.width) * 100,
+  y: (pixelPos.top / canvasSize.height) * 100,
+  w: (pixelPos.width / canvasSize.width) * 100,
+  h: (pixelPos.height / canvasSize.height) * 100,
+});
+
+/**
+ * Chuyển đổi tọa độ từ % sang Pixel thực tế trên thiết bị.
+ * AC 1: Renderer phải tính toán vị trí dựa trên % từ JSON
+ */
+export const calculateRealPosition = (
+  percentPos: { x: number; y: number; w: number; h: number },
+  screenSize: { width: number; height: number },
+) => ({
+  left: (percentPos.x * screenSize.width) / 100,
+  top: (percentPos.y * screenSize.height) / 100,
+  width: (percentPos.w * screenSize.width) / 100,
+  height: (percentPos.h * screenSize.height) / 100,
+});

package/src/sync/action-manager.ts

@@ -0,0 +1,23 @@
+import type { ActionLog } from "../index.js";
+
+/**
+ * Quản lý hàng đợi hành động để đồng bộ Offline.
+ * Cơ chế Action Log (Tránh mất dữ liệu)
+ */
+export const filterActionsToSync = (
+  localActions: ActionLog[],
+  lastSyncAtServer: number,
+): ActionLog[] => {
+  // AC 1: Chỉ gửi lên Server những hành động có timestamp lớn hơn thời điểm đồng bộ cuối
+  return localActions.filter((action) => action.timestamp > lastSyncAtServer);
+};
+
+/**
+ * Xử lý xung đột theo quy tắc Last Sync Wins.
+ */
+export const resolveSyncConflict = (
+  localTimestamp: number,
+  serverTimestamp: number,
+): boolean => {
+  return localTimestamp > serverTimestamp;
+};

package/src/types/actions.ts

@@ -0,0 +1,83 @@
+/**
+ * Tập hợp các sự kiện (events) từ người dùng hoặc hệ thống
+ * dùng để kích hoạt một hành động (action) nào đó trên Slide.
+ */
+export const ACTION_TRIGGERS = {
+  ON_CLICK: "ON_CLICK",
+  ON_DOUBLE_CLICK: "ON_DOUBLE_CLICK",
+  ON_HOVER: "ON_HOVER",
+  ON_ENTER_VIEWPORT: "ON_ENTER_VIEWPORT",
+} as const;
+
+export type ActionTrigger =
+  (typeof ACTION_TRIGGERS)[keyof typeof ACTION_TRIGGERS];
+
+/**
+ * Danh sách các loại hành động (side-effects) mà hệ thống hỗ trợ thực thi.
+ * Ví dụ: Chuyển trang, ẩn hiện component, phát nhạc, hoặc nộp bài.
+ */
+export const ACTION_TYPES = {
+  NAVIGATE_SLIDE: "NAVIGATE_SLIDE",
+  TOGGLE_VISIBILITY: "TOGGLE_VISIBILITY",
+  PLAY_MEDIA: "PLAY_MEDIA",
+  EVALUATE_ANSWER: "EVALUATE_ANSWER",
+} as const;
+
+export type ActionType = (typeof ACTION_TYPES)[keyof typeof ACTION_TYPES];
+
+/**
+ * Payload: Dữ liệu cấu hình cho hành động chuyển slide.
+ * - `targetSlideId`: ID của slide muốn nhảy tới (Dùng cho điều hướng tự do).
+ * - `direction`: Điều hướng tuần tự (Tiến/Lùi).
+ */
+export interface NavigatePayload {
+  targetSlideId?: string;
+  direction?: "NEXT" | "PREV";
+}
+
+/**
+ * Payload: Dữ liệu cấu hình cho hành động thay đổi trạng thái hiển thị của Element.
+ * - `targetElementId`: ID của phần tử bị tác động.
+ * - `action`: Trạng thái muốn áp dụng (Hiển thị / Ẩn / Đảo ngược trạng thái).
+ */
+export interface ToggleVisibilityPayload {
+  targetElementId: string;
+  action: "SHOW" | "HIDE" | "TOGGLE";
+}
+
+/**
+ * Payload: Dữ liệu cấu hình cho hành động chấm điểm và tính toán Spaced Repetition.
+ * - `targetElementId`: (Tùy chọn) ID của bài tập (Quiz, Matching,..) cần chấm. Nếu nút bấm nằm rời bên ngoài.
+ * - `conceptId`: (Tùy chọn) ID của kỹ năng/khái niệm để lưu tiến độ (mastery) cho học viên.
+ */
+export interface EvaluatePayload {
+  targetElementId?: string;
+  conceptId?: string;
+}
+
+/**
+ * Từ điển ánh xạ (Mapping Map) cực kỳ quan trọng.
+ * Định nghĩa chính xác ActionType nào thì phải xài chung với Payload Interface nào.
+ */
+export type ActionPayloadMap = {
+  [ACTION_TYPES.NAVIGATE_SLIDE]: NavigatePayload;
+  [ACTION_TYPES.TOGGLE_VISIBILITY]: ToggleVisibilityPayload;
+  [ACTION_TYPES.PLAY_MEDIA]: { mediaUrl: string; loop: boolean };
+  [ACTION_TYPES.EVALUATE_ANSWER]: EvaluatePayload;
+};
+
+/**
+ * Cấu trúc hoàn chỉnh của một Hành động gắn vào Element.
+ *
+ * @description Sử dụng pattern "Discriminated Union" của TypeScript:
+ * Khi dev set thuộc tính `type`, TypeScript sẽ tự động ép buộc `payload`
+ * phải chứa các trường dữ liệu tương ứng được định nghĩa trong `ActionPayloadMap`.
+ * Tránh tuyệt đối việc râu ông nọ cắm cằm bà kia (VD: type là NAVIGATE nhưng truyền mediaUrl).
+ */
+export type ElementAction = {
+  [K in ActionType]: {
+    trigger: ActionTrigger;
+    type: K;
+    payload: ActionPayloadMap[K];
+  };
+}[ActionType];

package/src/types/common.ts

@@ -0,0 +1,9 @@
+/**
+ * Cấu trúc tọa độ cơ bản dựa trên tỷ lệ %.
+ */
+export interface Position {
+  x: number; // Tọa độ ngang (0-100)
+  y: number; // Tọa độ dọc (0-100)
+  w: number; // Chiều rộng (0-100)
+  h: number; // Chiều cao (0-100)
+}

package/src/types/data.ts

@@ -0,0 +1,71 @@
+// --- Standard Element Data ---
+
+export interface TextData {
+  content: string;
+}
+
+export interface VideoData {
+  src: string;
+  poster?: string;
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  controls?: boolean;
+  isLive?: boolean;
+}
+
+// --- Game Element Data ---
+
+// 1. Multiple Choice: Chọn 1 đáp án đúng
+export interface MultipleChoiceData {
+  question: string;
+  options: { id: string; content: string }[];
+  correctId: string;
+}
+
+// 2. Sorting: Sắp xếp theo thứ tự mảng
+export interface SortingData {
+  items: { id: string; content: string }[];
+  correctOrder: string[]; // Mảng chứa các ID theo thứ tự đúng
+}
+
+// 3. Matching: Nối cặp A - B
+export interface MatchingData {
+  leftColumn: { id: string; content: string }[];
+  rightColumn: { id: string; content: string }[];
+  correctPairs: [string, string][]; // Mảng các cặp [id_trái, id_phải]
+}
+
+// 4. Hotspot: Click vào vùng ảnh
+export interface HotspotData {
+  imageUri: string;
+  zones: {
+    id: string;
+    xMin: number;
+    yMin: number; // Đơn vị %
+    xMax: number;
+    yMax: number;
+  }[];
+  correctZoneId: string;
+}
+
+// --- Data Maps ---
+
+/**
+ * Map để liên kết các Game Type với dữ liệu tương ứng.
+ */
+export type GameDataMap = {
+  QUIZ: MultipleChoiceData;
+  SORTING: SortingData;
+  MATCHING: MatchingData;
+  HOTSPOT: HotspotData;
+  MEMORY_CARD: any; // Có thể mở rộng thêm sau
+};
+
+/**
+ * Map tổng hợp giữa tất cả ElementType và cấu trúc data tương ứng.
+ */
+export type ElementDataMap = GameDataMap & {
+  TEXT: TextData;
+  VIDEO: VideoData;
+};

package/src/types/elements.ts

@@ -0,0 +1,77 @@
+import type { ElementAction } from "./actions.js";
+import type { Position } from "./common.js";
+import type { ElementDataMap } from "./data.js";
+
+/**
+ * Định nghĩa tất cả các loại phần tử có thể xuất hiện trong một Slide.
+ */
+export const ELEMENT_TYPES = {
+  TEXT: "TEXT",
+  VIDEO: "VIDEO",
+  QUIZ: "QUIZ",
+  MATCHING: "MATCHING",
+  SORTING: "SORTING",
+  MEMORY_CARD: "MEMORY_CARD",
+  HOTSPOT: "HOTSPOT",
+} as const;
+
+export type ElementType = (typeof ELEMENT_TYPES)[keyof typeof ELEMENT_TYPES];
+
+/**
+ * Định nghĩa các loại game (tập con của ELEMENT_TYPES).
+ */
+export const GAME_TYPES = {
+  QUIZ: "QUIZ",
+  MATCHING: "MATCHING",
+  SORTING: "SORTING",
+  MEMORY_CARD: "MEMORY_CARD",
+  HOTSPOT: "HOTSPOT",
+} as const;
+
+export type GameType = Extract<
+  ElementType,
+  (typeof GAME_TYPES)[keyof typeof GAME_TYPES]
+>;
+
+/**
+ * Định nghĩa style cho một phần tử.
+ */
+export interface ElementStyle {
+  backgroundColor?: string;
+  color?: string;
+  fontSize?: number;
+  fontFamily?: string;
+  fontWeight?: string | number;
+  textAlign?: "left" | "center" | "right" | "justify";
+  border?: string;
+  borderRadius?: number;
+  opacity?: number;
+  zIndex?: number;
+  [key: string]: any; // Allow other CSS properties
+}
+/**
+ * Định nghĩa các loại animation hỗ trợ
+ */
+export interface ElementAnimation {
+  type: "fade-in" | "slide-up" | "bounce" | "zoom-in";
+  duration: number; // Tính bằng ms
+  delay: number; // Độ trễ trước khi chạy (ms)
+  repeat?: boolean;
+}
+
+/**
+ * Sử dụng Discriminated Union để đảm bảo type-safety cho thuộc tính 'data'.
+ */
+export type SlideElement = {
+  [K in keyof ElementDataMap]: {
+    id: string;
+    type: K;
+    position: Position;
+    style?: ElementStyle;
+    enterAnimation?: ElementAnimation;
+    exitAnimation?: ElementAnimation;
+    actions?: ElementAction[];
+    data: ElementDataMap[K];
+    groupId?: string;
+  };
+}[keyof ElementDataMap];

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./common.js";
+export * from "./data.js";
+export * from "./elements.js";
+export * from "./models.js";
+export * from "./actions.js";

package/src/types/models.ts

@@ -0,0 +1,47 @@
+import type { SlideElement } from "./elements.js";
+
+// --- Slide Models ---
+
+export interface SlideConfig {
+  aspectRatio: string;
+  theme: string;
+}
+
+export interface Slide {
+  id: string;
+  tenant_id: string;
+  course_id: string;
+  order: number;
+  config?: SlideConfig;
+  elements: SlideElement[];
+}
+
+// --- Tracking & Progress Models ---
+
+export const CONFIDENCE_LEVELS = {
+  HIGH: "High",
+  MEDIUM: "Medium",
+  LOW: "Low",
+} as const;
+
+export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[keyof typeof CONFIDENCE_LEVELS];
+
+export interface ActionLog {
+  action_type: string;
+  timestamp: number;
+  duration: number;
+  result: {
+    is_correct: boolean;
+    confidence: ConfidenceLevel;
+  };
+}
+
+export interface UserProgress {
+  user_id: string;
+  tenant_id: string;
+  concept_id: string;
+  streak: number; // Số lần đúng liên tiếp
+  is_mastered: boolean;
+  next_review_at: string; // ISODate string
+  last_sync_at: string; // ISODate string
+}

package/tsconfig.json

@@ -0,0 +1,44 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}