# DocuDeck Player desktop

The Electron application provides a personal offline course library: batch ZIP import, folders, drag-to-folder moves, search, favorites, recent courses, course details, grid/list views, English/Arabic with RTL, and light/dark/system appearance. Imported courses run in a separate sandboxed player window. SQLite stores progress and answers on the device. Laravel, MySQL, a server account, and internet are not required for local playback.

## Run

From `scorm_player`:

```powershell
npm ci
npm ci --prefix frontend
npm run desktop
```

Use **Import courses** or drop multiple ZIP files into the library. Create folders using **New folder**. Drag a course onto a folder, or use **Course details → Move to folder**. Deleting a folder moves courses to Uncategorized and keeps their progress. Removing a course requires confirmation and deletes its local copy and progress; the original ZIP is retained.

Opening a course launches its authored player. Use its outline, media, quiz, and H5P controls. Close the course window to return to the library; the Course menu also offers Back to library and Fullscreen. Progress is checkpointed every five seconds and on SCORM commit/normal close. Uncommitted activity-specific answers depend on what the authored course saves. Sudden termination can lose work since the last successful checkpoint.

## Supported content

This release accepts **DocuDeck-generated SCORM 1.2 ZIPs with a single SCO and a root `imsmanifest.xml`**. General third-party SCORM compatibility, SCORM 2004, multi-SCO sequencing, mobile, and result synchronization are outside this release.

Known online dependencies prompt an import warning; internet requests are blocked during playback. Replace YouTube/external content with uploaded local media in the authoring app. Static scanning cannot certify every arbitrary script as fully offline. Media playback depends on codecs supported by the packaged runtime; test your actual files on each target OS.

Identical ZIPs are detected without adding another course. A changed ZIP with the same manifest identifier prompts to keep a separate version, preserving the original course and its answers. Versions do not share progress. The library's slides-viewed indicator is distinct from completion: assessments and required activities still govern the SCORM status.

## Architecture and storage

- `frontend/src`: React interface; shared modal, library components, settings, localization, and design tokens.
- `desktop/main`: Electron lifecycle, scoped IPC handlers, and playback orchestration.
- `desktop/preload`: typed app bridge and a separate course bridge exposing only SCORM methods.
- `desktop/services`: embedded SQLite, scoped local content delivery, and SCORM session tracking.
- `desktop/workers`: archive hashing, validation, extraction, and external-dependency scanning.
- `packages/course-core`: reusable interpretation of DocuDeck slide progress.
- `backend`: existing independent Laravel online administration and SSO, unchanged by desktop playback.

Course files, staging imports, and `library.sqlite` live in Electron's OS application-data directory for DocuDeck Player. This is independent of the existing Laravel/MySQL database. Database upgrades are additive, newer database versions are rejected by older apps, and a single-instance lock prevents simultaneous writers. Application upgrades retain user data. Automatic updates are not implemented.

For an isolated development/test profile, set `SCORM_PLAYER_DATA_DIR` to an absolute directory before launch. Never point it at server data. Back up the complete application-data directory while the app is closed if you need to preserve a local library externally.

The main process serves each course over an ephemeral `127.0.0.1` HTTP port with an unguessable path token, host/origin checks, read-only routing, and course-root restrictions. This is local device traffic; no internet server is involved. HTTP URLs preserve H5P URL compatibility. Course scripts have no native filesystem privileges, and external navigation, permissions, and network requests are restricted. Media streams with byte-range support. Worker imports enforce a 30,000-file / 8 GB extraction limit and clean up cancellation/failure staging directories.

## Validate and package

```powershell
npm test
npm --prefix frontend run lint
npm run test:performance
npm run pack
npm run test:packaged
npm run dist
```

Version 0.1.1 fixes separate H5P screens sharing space with hidden slides and keeps small activities visible with internal scrolling instead of an expand-only placeholder. Existing desktop courses receive the corrected shell visibility rule and shared H5P bridge at playback without rewriting their files, placement settings, IDs, or answers. The build copies the canonical authoring bridge into `desktop/compat`; that generated directory is packaged but Git-ignored. Future course exports also include the source fix. Already exported packages used outside this desktop player need to be re-exported to receive it.

`npm run test:layout` checks full-stage activity screens, inline placement, readable content, expansion, and export visibility CSS. To reproduce a particular installed course, set `SCORM_LAYOUT_COURSE_DIR` to its extracted directory; the test reads it and creates an isolated temporary copy. It does not change the original library. Run the build first to synchronize the shared bridge.

`pack` creates an unpacked application under `release`; `dist` creates installers for the host platform. Targets are Windows NSIS, macOS DMG, and Linux AppImage/DEB. Branding assets are checked in under `desktop/build`; regenerating them uses the optional Pillow script there. Use Node 22.12+; CI uses Node 24. Install both root and frontend dependencies from their lockfiles.

The acceptance script imports a tracking/media fixture and the repository's real eight-type H5P course, tests isolated playback, media seeking, progress/reload/restart, and takes screenshots. Its original tiny H.264/AAC fixture is checked in; FFmpeg is not required to run tests. `test-results` contains local screenshots and JSON evidence and is Git-ignored. The synthetic 256 MB import profile records measurements and their limitations rather than promising identical results on other devices.

The [desktop CI workflow](../.github/workflows/scorm-player-desktop.yml) configures Windows, Linux, and macOS packaging/acceptance. Linux desktop tests use Xvfb. Configuration is not proof that another OS has passed: record actual results separately. Windows output from this workspace is unsigned. Public distribution still requires appropriate signing credentials and macOS notarization. No signing secrets are stored in the repository.

See [the implementation plan](DESKTOP_IMPLEMENTATION_PLAN.md) and [validation record](DESKTOP_VALIDATION.md) for delivery status and remaining acceptance work.
