# SCORM editor and learner theme migration

Local implementation of the approved `frontend_prototype/` design in the production React editor and learner player. The prototype remains a reference; its sample content, simulated requests and storage are excluded from production.

## React structure

The editor route and `tool-client.tsx` remain compatibility entry points. Existing `Conversion`, `Settings` and `Slide` type exports continue to work.

Production modules live in `documents_generator_tools_frontend/app/tools/powerpoint-to-scorm/studio/`:

| Module | Responsibility |
| --- | --- |
| `editor-workspace.tsx` | Project tabs, visited sessions, History API navigation, metadata restoration, all-project leave/logout guards and confirmation hosting. |
| `editor-project.tsx` | Compose one project's header, navigation, slide library, panels, preview and conversion states. |
| `editor-header.tsx`, `project-tabs.tsx`, `project-picker.tsx`, `editor-navigation.tsx`, `slide-library.tsx` | Reusable workspace presentation and typed interactions. |
| `player-settings.tsx`, `animation-settings.tsx`, `course-structure-panel.tsx`, `questions-panel.tsx`, `media-panel.tsx`, `files-media-panel.tsx` | Existing authoring controls separated from the page. |
| `use-editor-session.ts` | Per-project authoring documents, revisions, loading, mutations, uploads, polling and autosave orchestration, independent of presentation. |
| `use-save-coordinator.ts`, `use-session-api.ts`, `use-nested-drafts.tsx` | Save transaction coordination, disposed-session request protection, and narration/layout/preparation integration with draft guards. |
| `use-preview-activity.ts`, `use-preview-focus.ts`, `previews.tsx` | Preview activity, focus lifecycle and the existing author preview behavior. |
| `project-api.ts`, `types.ts`, `context.tsx` | Typed project queries, shared editor contracts and project-session interfaces. |
| `confirmation-boundary.tsx` | Styled confirmations for standalone and public learner previews. |
| `studio.css`, `learner.css`, `i18n.ts` | Scoped warm surfaces, forest typography, terracotta authoring actions, responsive presentation and new English/Arabic copy. |

The editor reuses production workspace icons, dialogs, authentication and API utilities. Sharing continues through the existing dashboard sharing interface, with the existing project capabilities and global sharing switch. Dialog focus restoration also supports closed or hidden project sessions.

## Feature parity

| Area | Existing behavior retained |
| --- | --- |
| Player | Appearance, title, selected accent, language/direction, navigation/menu, progress, viewing rules, timers and completion controls. |
| Course structure | Source/image slides, ordering, inclusion, menu visibility, removal/restoration, dependency feedback and per-slide narration. |
| Questions | Question types/options, groups, scoring, attempts, presentation, selective inheritance/adoption, moving, duplication and restoration. |
| Media | Uploads/replacement/retry, YouTube, placement/layers/popups, playback and controls, completion requirements, captions, icons, dependencies and ZIP narration import. |
| Files & Media | Existing managed-file operations, resource downloads, AI narration scripts/audio, generation and error/conflict feedback. |
| Animations | Overall transitions and independent slide overrides, with the existing live preview behavior. |
| Fonts & rendering | Preparation language/direction, font permission and fallback acknowledgments, uploads/removal and regeneration. |
| Layout correction | Geometry, typography, canvas modes, original/corrected previews, zoom/pan/snap, keyboard operations, undo/redo, revision locks and save/preview controls. |
| Conversion lifecycle | PPTX upload, preparation, processing, failure, preview, package generation, completed state and authorized ZIP download. |

These are retained controls and contracts, not a claim that every combination has received live-browser QA. Interaction tests exercise the new workspace and selected controls; existing source assertions, pure-function tests and isolated backend regressions provide additional coverage.

## Tabs and save safety

- Opening a project already in the workspace selects its tab. The project picker uses owned/shared API listings with server search and pagination.
- Visited sessions remain mounted. Each owns its documents, drafts, selected section/slide, save state and processing state. Ordinary document autosave retains its 800 ms debounce; narration retains its 750 ms debounce. Background authoring saves and processing polling continue independently.
- `sessionStorage` stores only ordered project IDs, section and slide under `docudeck:editor-tabs:<user-id>`. Refresh reloads server content; inactive restored projects load when visited. Upload-only tabs are not persisted. No authoring drafts, credentials, share tokens or signed asset URLs are stored.
- UUID URLs, direct links, refresh and Back/Forward work through the existing routes and a minimal History API adapter. Leaving the editor, opening account/sharing screens or logging out checks drafts and pending operations across all open projects.
- Dirty close offers **Save and close**, **Discard unsaved changes**, and **Keep open**. Save failures retain the tab and draft. Discard keeps changes already persisted. Pending operations block disposal until they finish.
- Narration scripts and layout corrections participate in dirty-state and save guards. Layout inspector state survives project switching. Inactive layout keyboard handlers and preview countdowns/playback pause; inactive dialogs do not take focus.
- Save entry points join a per-project transaction, preserve existing revision payloads/order, and protect newer edits against older responses. Existing revision conflicts remain visible. No conflict handler silently reloads over a local draft.
- Activation revalidates access. Revocation, deletion or a lost editing capability blocks the authoring surface while retaining local work. **Retry**, or selecting the tab again, revalidates access. Saving without access fails and keeps the tab open.
- Viewing, editing, package availability, downloading and sharing continue to follow independent server capabilities.

## Learner and exported packages

`final-scorm-preview.tsx` uses the learner theme through the same player used by public-share routes. The theme changes chrome, menus, navigation, progress and default surrounding surfaces. Project-selected accents, question settings, fonts, authored media styles/placement, slide content and animations remain authoritative.

The exported player change is limited to `documents_generator_tools_backend/resources/scorm-player/styles.css`. Runtime JavaScript, HTML DOM IDs, SCORM initialization, scoring, completion, attempts, resume data, timers, required-content gates, resources, manifest entries and package filenames are unchanged. The export adds no online theme assets.

Only newly built ZIPs receive the updated packaged styles. Existing generated/downloaded ZIPs are not rebuilt or modified automatically.

No endpoint, database, migration, environment, queue, credential-resolution or permission changes are included. No commit, push or deployment was performed.

## Local validation — 2026-10-12

- Production TypeScript check and Vite build passed.
- All **128 frontend tests passed**, including **25 new React editor interaction tests**. These cover tab deduplication/restoration, UUID/history navigation, isolated drafts, background autosave, stale save responses, close/leave/logout guards, failures/conflicts, narration/layout drafts, access revocation/restoration, all seven sections, sharing-disabled behavior, viewer capabilities, picker request disposal, PPTX multipart upload, authenticated ZIP download, Arabic/RTL interaction and learner countdown suspension/navigation.
- Existing frontend tests retain their behavioral assertions and now locate the extracted editor modules through `tests/helpers/editor-sources.mjs`.
- Focused ESLint passed with **zero errors or warnings** for new/refactored editor modules, shared dialog changes, route changes and affected tests. Full application lint reports **one existing error, no warnings**, in unchanged `app/auth/shared-project-page.tsx:29`; the previous baseline was 12 errors and 5 warnings.
- **88 backend tests passed with 887 assertions**, using SQLite in memory: account/project, folders, sharing, ultimate-admin access, course composition, layout, preparation, conversion, questions, media, narration and package construction. Package/scoring coverage includes zero-point assessments. No application database reset or migration was run.
- Editor, learner, layout and exported-player CSS parsed successfully with PostCSS. `git diff --check` passed.
- Existing dependencies were preserved. The test build emits the existing Node `module.register()` deprecation notice.

Repeat frontend validation from `documents_generator_tools_frontend/`:

```powershell
npm test
npx eslint app/tools/powerpoint-to-scorm app/workspace/components/ui.tsx src/main.tsx tests/editor-workspace.test.mjs tests/helpers/editor-sources.mjs tests/files-media.test.mjs tests/localization.test.mjs tests/rendered-html.test.mjs tests/scorm-player.test.mjs tests/fixtures/workspace.tsx
npm run lint
```

Repeat backend checks from `documents_generator_tools_backend/`, after confirming `bootstrap/cache/config.php` is absent and that the test process is isolated:

```powershell
$env:APP_ENV = 'testing'
$env:DB_CONNECTION = 'sqlite'
$env:DB_DATABASE = ':memory:'
$env:DB_URL = ''
& 'C:/laragon/bin/php/php8.3/php.exe' -d extension=php_pdo_sqlite.dll -d extension=php_sqlite3.dll vendor/bin/phpunit --filter 'AccountAndProjectTest|ProjectFolderTest|ProjectSharingTest|UltimateAdminAccessTest|StageSevenCourseCompositionTest|SlideLayoutTest|PreparationTest|PowerPointToScormConversionTest|PowerPointToScormQuizTest|PowerPointToScormMediaTest|PowerPointToScormNarrationTest|ScormPackageBuilderTest'
```

## Question-tool design follow-up — 2026-10-12

- Applied the prototype's warm fields, compact buttons, outline question/search/layer icons, green inheritance toggles, and reusable native disclosure sections to the production question inspector. Group and course-flow tools remain available, with a stacked toolbar and group menus that fit the inspector.
- Kept question state, autosave callbacks, grouping, scoring, placement, effective-setting resolution, removal/restoration, and API payloads unchanged. Added localized answer input/removal labels.
- The existing 128-test frontend suite passed. Two additional focused React interaction tests passed for drafts across disclosure/settings navigation and preserving content/freezing effective settings when group inheritance is disabled. Production build, affected-module/test lint, CSS parsing, and whitespace checks passed.
- Used local headless Chrome to inspect isolated production-component renders with test fixtures: English at 460px and Arabic/RTL at 340px. Both had page widths equal to viewport widths, with no horizontal overflow. These checks used static rendered components; they do not constitute authenticated application or live-project validation. QA HTML/screenshots are under the ignored frontend `out/` directory.

## Course structure design follow-up — 2026-10-12

- Replaced the legacy two-panel composition with the prototype's narrow slide library, central image preview, and selected-slide inspector. Kept summary counts, search/filter controls, keyboard move buttons, pointer sorting, add/remove/restore, duplication choices, inclusion/menu switches, attachment safeguards, and save feedback.
- The central preview uses the selected slide's real image and project aspect ratio. Narration editing moved from every library card into the selected-slide inspector; values and save states remain controlled by the existing per-slide narration document and handlers. AI generation remains in Files & Media.
- Extracted reusable preview and narration components. Questions and Course structure now share `EditorSettingsSection`; the existing `QuestionToolSection` export remains compatible.
- Added React interaction coverage for selection and isolated narration drafts, real-image/aspect-ratio preview, ordering, duplicate options, image upload/blank creation, restoration, and attachment confirmations. Updated source-location assertions for extracted narration and the new responsive composition.
- Production build and all **133 frontend tests passed**. ESLint passed for all affected modules and tests with no errors or warnings; scoped CSS parsing and `git diff --check` passed.
- Chrome visual checks used isolated production-component renders with test data in English (1900px, 1100px, 390px) and Arabic/RTL (1900px, 390px), including legacy CSS loaded last. No horizontal page overflow occurred. Live project actions and physical pointer dragging remain unverified in an authenticated browser.

## New project dialog follow-up — 2026-10-12

- The dashboard and editor's new-project route now reuse the prototype's two-step type chooser and presentation-upload dialog. The dialog supports native file selection, drag-and-drop, an optional project title, retry feedback, and English/Arabic labels. Pending submissions block dismissal and repeated submission.
- Upload continues through the authenticated conversion endpoint. An optional validated `course_title` is saved with the conversion and initial player settings; omitting it preserves the filename-based default. Creation opens the returned project UUID for preparation.
- Production build, focused lint, and all 135 frontend tests passed. The 10 backend conversion tests passed with 87 assertions. A live local Chrome check confirmed the English desktop chooser and upload-dialog layout; no real presentation was submitted during browser QA.

## Remaining manual checks

Full authenticated browser QA remains unperformed. The question-tool and Course structure follow-ups used local Chrome for isolated component rendering. jsdom tests real React interactions and mocked request contracts; it does not verify native dialog top-layer behavior, physical pointer geometry, full browser Back/Forward navigation or browser downloads.

Before deployment, manually compare English/Arabic desktop/mobile views with the prototype, keyboard/focus behavior and 200% zoom. Exercise every authoring mutation and selective inheritance combination, real media/ZIP uploads, narration/provider generation and layout rendering. Complete upload → preparation → editing → preview → ZIP with the application's configured renderer/workers. Test separate-session access revocation, public-share playback and actual media/resources.

Moodle SCORM initialization, resume/completion/attempt reporting, exported-player playback and visual consistency against React preview were not tested in a live Moodle instance. Existing automated runtime/package checks passed; live renderer, provider and Moodle validation remains outstanding.