# SCORM Player desktop implementation plan

Status: Main functionality implemented; Windows packaging and local acceptance available. Full cross-platform release acceptance remains open. See DESKTOP_VALIDATION.md for actual evidence and remaining checks.

## Goal and delivery model

Build a polished offline desktop learning application inside the existing `scorm_player` project using Electron, React, and TypeScript. Learners can import multiple SCORM packages, organize them into folders, complete courses without internet, and resume with their progress preserved.

Deliver the main experience in **one integrated implementation stage**. The workstreams below describe execution order within that stage, not separate product releases. Import, library organization, playback, persistence, interface quality, and desktop packaging must work together before the stage is complete.

## Scope

- Target Windows, macOS, and Linux laptops and desktop computers.
- Start with DocuDeck-generated SCORM 1.2 packages containing a single SCO (the course's launchable learning module).
- Support packaged slides, images, video, audio, narration, captions, downloadable resources, quizzes, and supported bundled H5P activities.
- Support multiple imported courses with independent progress and attempts.
- Provide a personal course library, folders, search, recent courses, favorites, and uncategorized courses.
- Make local import, organization, playback, and progress saving available without an account or internet connection.
- Provide English and Arabic interfaces, including correct RTL layout and punctuation.

Mobile apps have a separate future plan. General compatibility with arbitrary third-party SCORM packages, SCORM 2004, multi-SCO sequencing, online course distribution, LMS result synchronization, and account-based offline licensing are outside this stage. Detect unsupported packages and explain the limitation before import completes.

## Existing foundation

The existing player contains a React/TypeScript/Vite frontend, a Laravel backend, administration, and DocuDeck sign-in. The frontend currently shows a coming-soon page; course import, playback, and tracking are not implemented there yet.

The authoring application already exports its browser course runtime, uploaded media, quiz functionality, and bundled H5P runtime/content. Reuse the exported runtime rather than recreating its authored activities in the desktop interface. Preserve existing authored behavior, tracking keys, scoring, and completion rules.

The existing web member session periodically checks DocuDeck online. Local desktop playback must have its own lifecycle and must not depend on that web session. Retain the backend for existing online services; learners must not need PHP, Laragon, or MySQL installed.

## Learner experience

### Application layout

- Left sidebar: Home, All courses, Recent, Favorites, Uncategorized, user folders, and Settings.
- Main area: course cards or list view, search, sorting, and an obvious Import course action.
- Breadcrumbs when browsing a folder, such as `My Library / Skills`.
- Home emphasizes Continue learning, followed by recently opened courses.
- Cards show a title, cover or fallback artwork, progress, and a Start or Continue action.
- Course details show title, available description, package size, import date, progress, and launch controls. Do not invent course duration when the package does not provide it.

### Import

1. Choose one or more SCORM ZIP files using a file picker or drag-and-drop.
2. Choose a destination folder, or import directly into the folder currently open.
3. Show a per-package import queue with progress, cancellation, and errors.
4. Validate the manifest, launch target, supported format, archive paths, required files, available disk space, and configured extraction limits.
5. Extract into temporary app-managed storage; publish the course to the library only after successful validation and extraction.
6. Clean up cancelled or failed imports without leaving incomplete library entries.
7. Detect identical imports and package revisions. Offer explicit choices rather than silently duplicating or replacing content.
8. Identify known external dependencies and display an offline readiness result. Explain that arbitrary HTML cannot be exhaustively certified through static scanning alone.

An identical archive can be recognized by its hash. Use manifest identifiers plus a package fingerprint to distinguish course identity from imported revisions. Preserve progress for moves and identical imports. Do not automatically apply old answers to changed content; make update/attempt behavior explicit and retain recoverable prior records.

### Organization

- Import and keep multiple packages in the same library.
- Create and rename folders; support moving courses using drag-and-drop and an accessible menu.
- Use a flat folder hierarchy for this stage; nested folders can be added later.
- A course belongs to one folder or Uncategorized. Favorites and Recent are views of the same course, not duplicate copies.
- Moving or renaming library items does not reset course progress or change packaged tracking identifiers.
- Search across the library; support sorting by title, recently opened, and recently imported.
- Deleting a folder moves its courses to Uncategorized by default. Course deletion is a separate explicit action explaining whether files and progress will be removed.

### Playback

- Large content area with a collapsible outline, Back to library, fullscreen, and clear navigation.
- Preserve the course's authored appearance and controls. Avoid duplicate video/audio controls around an existing course player.
- Keep authored completion gates, assessment attempts, scoring, and H5P interaction behavior intact.
- Save progress automatically and resume the last committed location after app restart.
- Save when leaving a course and on normal shutdown, with periodic checkpoints so unexpected termination loses minimal work.
- Handle missing assets and playback failures with actionable messages and a route back to the library.
- Start with one active course playback session at a time; opening another course saves and releases the previous session.

### Visual and interaction quality

- Calm media-library style with clear typography, generous spacing, consistent icons, and restrained color.
- Shared design tokens and reusable components rather than page-specific styling conventions.
- Light/dark/system appearance, accessible contrast, visible focus, and keyboard navigation.
- Subtle transitions that respect reduced-motion preferences.
- Correct Arabic/English layout, text direction, alignment, and mixed-direction content.
- Designed empty, loading, import, error, offline-dependency, and completed states.
- Adapt gracefully to common desktop window sizes and OS window conventions.

## Architecture

Proposed structure; adapt names to repository conventions during implementation while preserving these boundaries:

```text
scorm_player/
├── backend/                     Existing Laravel online services
├── frontend/
│   └── src/
│       ├── app/                 Navigation, providers, layouts
│       ├── features/
│       │   ├── library/
│       │   ├── folders/
│       │   ├── import/
│       │   ├── player/
│       │   └── settings/
│       ├── components/          Shared interface components
│       └── styles/              Design tokens, themes, RTL
├── desktop/
│   ├── main/                    Electron lifecycle and windows
│   ├── preload/                 Narrow, typed app bridge
│   ├── services/                Database, imports, content loading
│   └── workers/                 Archive extraction and heavy work
├── packages/
│   ├── course-core/             Identity and package validation
│   ├── scorm-runtime/           SCORM API and tracking contracts
│   └── contracts/               Shared types and IPC schemas
└── tests/                       Integration and desktop acceptance
```

### Runtime responsibilities

- Electron main process: window management, authorized local file operations, local content routing, and orchestration.
- React renderer: application interface and presentation state.
- Preload: minimal validated commands/events for the trusted app UI; do not expose raw filesystem, SQL, process execution, or unrestricted IPC.
- Worker or utility process: hashing, ZIP inspection/extraction, and other expensive operations.
- SQLite: embedded metadata and durable progress database, accessed behind application services.
- App-managed course directory: extracted course files and media, separate from the SQLite database.
- Imported content: isolated course rendering context without native app privileges.

Use a maintained Electron release, reproducible dependency installation, and migrations for the local database. Preserve existing backend data and authentication contracts.

### Local data model

Model courses, package versions, folders, local learner identity, attempts, SCORM values, and application preferences. Keep progress scoped to learner, course version, and attempt even though the first interface exposes one local learner profile.

Use stable internal IDs, package hashes, manifest identifiers, launch paths, and timestamps. Keep media as files on disk rather than database blobs or Base64 strings. Use transactions for metadata updates and recover cleanly after interrupted imports. Store data in the OS application-data location and retain it across application upgrades.

### SCORM and content integration

- Provide the SCORM 1.2 `window.API` expected by the course, including initialization, value access, commit, finish, and error reporting needed by supported packages.
- Preserve synchronous SCORM method behavior using in-memory session state, with durable checkpointing through the host. Do not replace the SCORM interface with asynchronous methods.
- Persist lesson location, suspend data, status, score, time, objectives, and interactions used by DocuDeck exports.
- Replace reliance on the exported preview fallback's shared localStorage key with properly scoped host tracking.
- Choose a local protocol/content-serving strategy that supports JavaScript modules, fetch, nested H5P pages, MIME types, captions, and video byte-range requests.
- Prototype the isolated content context and SCORM API bridge early: parent/opener API discovery, origin boundaries, and persistence must work together.
- Release video, audio, frames, listeners, and runtime state when switching or closing courses.

### Offline dependencies

Bundle local course assets. Flag YouTube, external embeds, remote fonts/scripts, and other network dependencies when detectable. Do not claim linked YouTube content is offline-capable or download it automatically.

For affected packages, explain which elements need internet and whether the learner wants to keep the package with that limitation. A fully offline acceptance course must have no required external resources.

### Imported-content isolation

Treat package HTML and JavaScript as untrusted. Enable sandboxing and context isolation, disable Node integration for course content, validate IPC senders and payloads, and keep course code away from privileged preload APIs. Restrict navigation, new windows, permissions, and access to other courses or local files.

Reject archive traversal, unsafe launch paths, symlink escapes, and excessive extraction sizes. The course content loader must enforce course-root boundaries. External links require deliberate handling outside the privileged app context.

## Performance requirements

- Keep hashing, extraction, and heavy validation off the UI thread and avoid blocking the main process.
- Stream large files and play media from disk; do not read complete courses or videos into renderer memory.
- Lazy-load course screens and artwork; use list virtualization if library measurements justify it.
- Batch/coalesce progress writes with bounded checkpoints and durable final commits.
- Provide responsive progress reporting and cancellation during imports.
- Measure packaged startup, import duration, UI responsiveness, memory, media seeking, and repeated course-switch behavior.
- Record representative test hardware and package sizes before setting numeric performance budgets. Do not promise unmeasured startup times or memory usage.

## One-stage execution checklist

All items belong to the same delivery stage. Checked items indicate implemented work with local Windows evidence; macOS/Linux runtime acceptance and signing remain separate release checks, as recorded in DESKTOP_VALIDATION.md.

- [x] Establish Electron development/build integration around the existing React frontend and typed main/preload boundaries.
- [x] Prove isolated playback of one real DocuDeck export, including SCORM API discovery, H5P, local fetch, video seeking, and durable resume.
- [x] Implement SQLite migrations, app-managed file storage, stable identities, and interrupted-operation recovery.
- [x] Implement safe batch import, cancellation, duplicate/version handling, and offline dependency reporting.
- [x] Build Home, course library, folders, details, search, sorting, favorites, and recent views.
- [x] Implement accessible folder/course actions and progress-preserving moves.
- [x] Complete the player shell, local tracking, automatic checkpoints, and error handling.
- [x] Apply the design system, light/dark themes, English/Arabic localization, RTL, keyboard behavior, and reduced motion.
- [ ] Profile large courses and repeated playback; resolve blocking operations and resource leaks.
- [x] Configure Windows, macOS, and Linux packaging, icons, app identity, and release builds; document signing/notarization requirements and available credentials.
- [x] Add focused validation for import safety, tracking persistence, version handling, and data migrations; run packaged end-to-end acceptance.
- [x] Update setup, architecture, build, supported-format, and learner documentation with verified limitations.

## Completion and acceptance

The stage is complete only when evidence shows:

1. Multiple supported packages can be imported together and remain available after restart.
2. Courses can be organized into Math, Skills, and other folders, moved, searched, favorited, and resumed independently.
3. Folder deletion preserves courses by moving them to Uncategorized; course removal follows its explicit deletion choice.
4. With networking disabled, a fully bundled sample plays slides, audio, video, captions, quizzes, and supported H5P activities.
5. Answers, scores, completion, and resume location survive navigation, normal restart, and tested interruption scenarios within the documented checkpoint behavior.
6. Two courses cannot overwrite each other's progress; changed package versions follow the documented attempt policy.
7. Large imports remain cancellable and the UI stays usable; video seeking works without loading the whole file into memory.
8. Invalid archives and unsupported packages fail clearly without escaping app storage or leaving broken entries.
9. Course scripts cannot access privileged native APIs or unrelated local files.
10. English/Arabic, RTL, themes, keyboard use, and common desktop window sizes pass visual/runtime review.
11. Packaged applications are installed and tested on Windows, macOS, and Linux. Report each OS separately; a successful Windows build is not proof of macOS/Linux support.
12. Existing online backend behavior remains intact and local learner data survives application upgrades.

Use real DocuDeck exports, including a media-rich course, the supported H5P activity set, and two separate courses with independent tracking. Record the tested OS/architecture, fixture versions, package sizes, results, and known limitations. Automated checks supplement actual packaged runtime tests.

## Build and release prerequisites

- Node/npm and Electron-compatible dependencies.
- Platform tooling for any native database module and packaging dependencies selected during implementation.
- Windows, Linux, and macOS build/test environments; macOS signing/notarization needs the appropriate Apple setup.
- Appropriate signing credentials where required for distribution. Never commit keys or credentials.
- Real representative machines or CI runners and actual playback testing on each target OS/architecture claimed as supported.

Select supported OS versions and CPU architectures against the chosen Electron release and document the matrix. Automatic application updates and cloud result synchronization are future work unless explicitly added to scope.

## Reference documentation

- Electron introduction and desktop platforms: https://www.electronjs.org/docs/latest/
- Electron security: https://www.electronjs.org/docs/latest/tutorial/security/
- Electron process model: https://www.electronjs.org/docs/latest/tutorial/process-model/
- Electron performance: https://www.electronjs.org/docs/latest/tutorial/performance/

Planning basis: repository source inspection and the product discussion. Architecture details are proposed implementation choices; cross-platform playback and performance remain to be validated during this stage.
