# Stage 1: Learner Progress Tracking ## Goal Allow a user to upload a PowerPoint presentation and download a SCORM 1.2 package with a well-designed slide player and learner progress tracking. ## User flow 1. The user uploads a `.pptx` file. 2. The application validates and processes the presentation. 3. Each PowerPoint slide is converted into a high-quality slide asset. 4. The user configures the SCORM player and progress settings. 5. The user previews the course experience. 6. The application generates a SCORM 1.2 ZIP package. 7. The user downloads the ZIP and uploads it directly to an LMS. ## PowerPoint processing - Accept `.pptx` files in this stage. - Keep the original slide order and aspect ratio. - Prioritize visual fidelity when converting slides. - Generate a full-size slide asset and thumbnail for every slide. - Show clear validation and processing errors. - Do not execute macros or external content. ## Course player - Responsive layout for desktop, tablet, and mobile. - Previous and Next controls. - Current slide and total slide count. - Learner progress bar. - Optional progress percentage. - Optional slide thumbnail or table-of-contents menu. - Optional course title in the player header. - Full-screen mode. - Keyboard and touch navigation. - Clear loading, beginning, end, and error states. ## Progress tracking Progress is calculated using unique slides viewed: > Progress percentage = unique required slides viewed / total required slides Moving directly to a later slide must not automatically count skipped slides as viewed. The SCORM package saves: - The current slide. - The unique slides already viewed. - The calculated progress percentage. - The last saved learner state. - An `incomplete` lesson status while the learner is progressing. Progress should be saved after important learner actions, including opening a new slide, using Previous or Next, selecting a slide from the menu, and leaving the course. Progress must continue to be tracked internally even when the visible progress bar, percentage, or slide counter is hidden. ## Display settings - Show or hide the progress bar. - Show or hide the current slide number. - Show or hide the progress percentage. - Show or hide the slide thumbnail menu. - Position the thumbnail menu vertically or horizontally. - Navigate a bounded thumbnail rail using a visible scrollbar or click-and-drag scrolling. - Show or hide the course title. - Show or hide the full-screen button. Recommended defaults: - Progress bar: shown. - Current slide number: shown. - Progress percentage: hidden. - Slide menu: shown. - Course title: shown. - Full-screen button: shown. ## Navigation settings ### Free navigation The learner can move directly to any slide. ### Sequential navigation The learner must visit slides in order. The learner can return to previously viewed slides but cannot skip forward to an unvisited slide. ### Timed navigation The Next button becomes available only after the configured minimum viewing time has elapsed. The slide menu can be configured to: - Allow opening any slide. - Allow opening only previously viewed slides. - Remain hidden. Returning to previous slides should be allowed by default. ## Minimum viewing time settings - Disable minimum viewing time. - Apply one duration to every slide. - Configure a different duration for individual slides. - Show or hide the countdown. - Unlock Next when the timer finishes. - Optionally move to the next slide automatically when the timer finishes. - Do not repeat the timer for a slide the learner has already completed. - Pause the timer when the course page is not visible or active. The preferred locked-button message is: > Available in 8 seconds The Next button should remain visible but disabled while locked. Hiding the button would make the navigation state unclear. Recommended default: - Minimum viewing time: disabled. - Automatic next slide: disabled. - Direct navigation: enabled. ## When a slide counts as viewed The course author can select one rule: - Immediately when the slide opens. - After its minimum viewing time finishes. - When the learner presses Next. When timed navigation is active, the recommended behavior is to count the slide as viewed only after its minimum viewing time finishes. ## Slide animation settings - Apply a global transition effect: None, Fade, Slide, or Zoom. - Choose Automatic, Left, Right, Up, or Down direction for the Slide effect. - Set a global duration from 100 to 2,000 milliseconds. - Override the effect and/or duration for individual slides; omitted values inherit the global setting. - Replay transitions on every visit, including the first slide. - Use two slide-image layers to prevent blank frames between slides. - Lock Previous, Next, slide-menu buttons, and keyboard navigation until the transition finishes. - Start slide tracking and minimum viewing timers only after the transition finishes. - Disable motion when the learner's device requests reduced motion. - Fall back to an immediate slide change if an image or animation fails. Recommended defaults: - Effect: Fade. - Direction: Automatic. - Duration: 400 milliseconds. The application animates the rendered slide images. Original PowerPoint object animations, audio synchronization, and video timelines are not reconstructed. ## Appearance settings - Light or dark player theme. - Primary player color. - Optional course logo. - Player language. - Left-to-right or right-to-left direction. - Slide background color. - Fit slide to screen or preserve its original display size. For the first implementation, only the primary color is required. The other appearance settings can be added without changing the tracking model. ## Settings preview - Show a live preview beside or after the settings form. - Update the preview when display settings change. - Demonstrate free, sequential, and timed navigation behavior. - Preview the disabled Next button and countdown. - Preview the selected progress display. - The preview must not require an LMS connection. ## SCORM package output - Generate SCORM 1.2 in this stage. - Produce a downloadable `.zip` file. - Include a valid `imsmanifest.xml`. - Include the course player, slide assets, thumbnails, settings, and SCORM communication code. - Allow the ZIP to be uploaded to an LMS without manual extraction or changes. - Use a safe filename based on the course title. ## Not included in Stage 1 - Quiz creation. - Quiz score tracking. - Pass or fail rules. - Detailed question or interaction tracking. - Multiple course modules. - Advanced completion rules. - SCORM 2004. - Native PowerPoint object animations and multimedia timelines. - Editable HTML slide reconstruction. - Resume confirmation interface. These features will be discussed and documented in their own stages before implementation begins. ## Acceptance criteria - A user can upload a valid `.pptx` file. - Every processed slide appears in the correct order and aspect ratio. - The user can configure the agreed display, navigation, timer, and progress settings. - The preview reflects the selected settings without an LMS connection. - Progress is based on unique viewed slides, not the highest slide number. - Hidden progress controls do not disable internal progress tracking. - Sequential navigation prevents skipping unvisited slides. - Timed navigation keeps Next disabled until the minimum time finishes. - Previously completed slides do not repeat their timer. - The application produces a downloadable SCORM 1.2 ZIP. - The generated course communicates and saves learner progress when launched inside a supported LMS. ## Local development setup Required software: - PHP and Composer for Laravel. - MySQL with a `documents_generator_tools` database. - Node.js 22.13 or newer. - LibreOffice with its headless console executable. - Poppler with `pdftoppm` available. Set these private Laravel environment values for the local machine: ```dotenv DB_CONNECTION=mysql DB_DATABASE=documents_generator_tools QUEUE_CONNECTION=database DB_QUEUE_RETRY_AFTER=1100 LIBREOFFICE_BINARY="C:/Program Files/LibreOffice/program/soffice.com" PDFTOPPM_BINARY="C:/path/to/poppler/Library/bin/pdftoppm.exe" FRONTEND_URL=http://localhost:3000,http://127.0.0.1:3000 ``` Run the Laravel API and its conversion queue separately: `````powershell cd documents_generator_tools_backend php artisan migrate php artisan serve ``` `````powershell cd documents_generator_tools_backend php artisan queue:work --queue=conversions --tries=2 --timeout=1000 ``` Run the React application from its frontend folder: ```powershell cd documents_generator_tools_frontend npm install npm run dev ``` The React app expects the API at `http://127.0.0.1:8000/api/v1` by default. Override it with `VITE_API_URL` when needed. Private sources, rendered slides, thumbnails, and the latest generated ZIP are stored under Laravel's private local disk and are not cleaned up automatically in Stage 1.