Time on slide: {Math.round(coursePlayer.slide.elapsedMs / 1000)}s
```
---
## SCORM State
```ts
import { scormState } from '$core/scorm';
```
### Properties
| Property | Type | Description |
| ------------------ | ------------------------------ | ------------------------------------------- |
| `isConnected` | `boolean` | SCORM API found |
| `isInitialized` | `boolean` | Successfully initialized |
| `version` | `'1.2' \| '2004' \| undefined` | Detected SCORM version |
| `mode` | `'lms' \| 'dev'` | Running against LMS or localStorage |
| `location` | `string` | Current slide path (read/write, auto-saved) |
| `sessionStartTime` | `number` | Timestamp when course started |
| `sessionElapsedMs` | `number` | Elapsed time (read-only) |
### Student Info
```ts
scormState.student.id; // learner ID from LMS
scormState.student.name; // learner name from LMS
```
### Session Info
```ts
scormState.session.mode; // 'normal' | 'browse' | 'review'
scormState.session.credit; // 'credit' | 'no-credit'
scormState.session.entry; // 'ab-initio' | 'ab_initio' | 'resume' | ''
```
### Methods
```ts
scormState.commit(); // force save to LMS
scormState.terminate(); // end session (called automatically on page unload)
```
---
## Quiz & Test System
The quiz system provides reusable `Question` and `Test` abstractions. Course authors define questions, group them into a test, and everything else — slide completion, weighted scoring, pass thresholds, and course score aggregation — is handled automatically.
### Question types
#### `defineMultiChoiceQuestion()`
```ts
import { defineMultiChoiceQuestion } from '$core/quiz';
const q = defineMultiChoiceQuestion({
id: 'my-question',
question: 'What does SCORM stand for?',
options: [
{ key: 'A', label: 'Shareable Content Object Reference Model' },
{ key: 'B', label: 'Standard Course Object Resource Manager' },
{ key: 'C', label: 'Synchronized Content Online Reference Module' },
{ key: 'D', label: 'Simple Course Object Runtime Model' }
],
correctAnswer: 'A',
weight: 2 // optional, default 1
});
```
#### `defineTrueFalseQuestion()`
```ts
import { defineTrueFalseQuestion } from '$core/quiz';
const q = defineTrueFalseQuestion({
id: 'tf-question',
question: 'SCORM 2004 supports sequencing and navigation.',
correctAnswer: 'true', // "true" or "false"
weight: 1 // optional, default 1
});
```
#### The `Question` interface
Both factories return an object conforming to `Question`. Future question types (fill-in, matching, etc.) implement the same interface.
| Property / Method | Type | Description |
| ----------------- | ----------------------- | ------------------------------------------------- |
| `id` | `string` | Short ID provided by the author |
| `fullId` | `string` | Globally unique: `q:{lessonId}:{slideId}:{id}` |
| `question` | `string` | Question text |
| `weight` | `number` | Weight for scoring (default 1) |
| `selectedAnswer` | `string \| undefined` | Writable reactive state — bind UI selections here |
| `isPassed` | `boolean` | Reactive: answered correctly |
| `attempts` | `RecordedInteraction[]` | All recorded attempts |
| `handleSubmit()` | `void` | Submits `selectedAnswer` to SCORM |
Set the user's selection directly on the question:
```svelte
```
### `defineTest()`
Groups questions into a test with weighted scoring and a pass threshold. The test **owns slide completion** — you never call `useSlideCompletion()` yourself.
```ts
import { defineMultiChoiceQuestion, defineTest } from "$core/quiz";
const q1 = defineMultiChoiceQuestion({ id: "q1", ..., weight: 2 });
const q2 = defineMultiChoiceQuestion({ id: "q2", ... });
const test = defineTest({
id: "knowledge-check",
questions: [q1, q2],
passThreshold: 0.5, // 50% to pass (0–1, default 1.0)
});
```
#### `TestHandle` properties and methods
| Property / Method | Type | Description |
| ------------------- | ---------------- | -------------------------------------------------- |
| `id` | `string` | Test ID |
| `fullId` | `string` | Globally unique: `test:{lessonId}:{slideId}:{id}` |
| `questions` | `Question[]` | All questions in the test |
| `score` | `number` | Weighted score 0–100% (reactive) |
| `isPassed` | `boolean` | Reactive: `score >= passThreshold * 100` |
| `isSubmitted` | `boolean` | Reactive: test has been submitted |
| `allAnswered` | `boolean` | Reactive: every question has a `selectedAnswer` |
| `hasIncorrect` | `boolean` | Reactive: submitted with at least one wrong answer |
| `passedCount` | `number` | Number of correctly answered questions |
| `answeredCount` | `number` | Number of questions with a selected answer |
| `questionResult(q)` | `QuestionResult` | `'correct'`, `'incorrect'`, or `undefined` |
| `submit()` | `void` | Submits all questions' `selectedAnswer`s |
| `retry()` | `void` | Clears submitted state and all selections |
#### What `defineTest()` handles automatically
1. **Slide completion** — calls `useSlideCompletion()` internally; marks the slide as passed (with score) or sets the score on failure
2. **Weighted scoring** — `score = (earned weight / total weight) * 100`
3. **Pass threshold** — `isPassed` when `score >= passThreshold * 100`
4. **Session restore** — if the test was already passed in a previous session, pre-fills `selectedAnswer` from persisted attempts
5. **Course score** — all tests automatically contribute to `scormState.score.raw` via the test registry (scaled to the course's `minScore`–`maxScore` range)
### Course score aggregation
Every `defineTest()` call registers the test with a global `testRegistry`. The registry:
- Averages all test scores into a single course score percentage
- Scales that percentage to the course's `minScore`–`maxScore` range and writes it to `scormState.score.raw`
- Calls `scormState.completion.setPassed()` when all tests pass
No manual wiring needed. If your course has two quiz slides each with a `defineTest()`, the course score is the average of their two scores.
### Full example
```svelte
{#each test.questions as q, qi (q.id)}
{@const result = test.questionResult(q)}
{qi + 1}. {q.question}
{#each q.options as option (option.key)}
{/each}
{#if result === 'correct'}
Correct!
{/if}
{#if result === 'incorrect'}
Incorrect — try again.
{/if}
{/each}
{test.answeredCount} of {test.questions.length} answered
{#if test.isPassed}
Passed — {Math.round(test.score)}%
{:else if test.hasIncorrect}
{test.passedCount} of {test.questions.length} correct
{:else}
{/if}
```
### Creating a new question type
To add a new question type (e.g., fill-in-the-blank):
1. Create `src/_core/quiz/define-fill-in.svelte.ts`
2. Export a factory that returns an object conforming to `Question`
3. Internally call `scormState.store.recordInteraction({ type: "fill-in", ... })`
4. Re-export from `src/_core/quiz/index.ts`
The new type works with `defineTest()` immediately — no changes to the test or scoring system.
---
## Course Score vs Slide Score
These are two separate concepts that serve different purposes.
### Course score (`scormState.score`)
The **course score** is the overall grade reported to the LMS via `cmi.core.score` (SCORM 1.2) or `cmi.score` (SCORM 2004). This is what the LMS displays in its gradebook.
```ts
scormState.score.raw; // get/set — clamped to [min, max]
scormState.score.min; // read-only (set from course definition)
scormState.score.max; // read-only (set from course definition)
scormState.score.scaled; // read-only, SCORM 2004 only (auto-calculated)
```
- Range defined by `minScore` / `maxScore` in `defineCourse()`
- If you use `defineTest()`, the course score is set automatically via the test registry (see [Quiz & Test System](#quiz--test-system))
- You can also set it manually for custom grading logic
- The LMS uses this alongside `masteryScore` to determine pass/fail
```ts
scormState.score.raw = 85;
// SCORM 1.2: raw = 85
// SCORM 2004: raw = 85, scaled = 0.85 (auto)
```
### Slide score (`useSlideCompletion().score`)
The **slide score** is a per-slide value (0–100) stored in SCORM objectives. It is used internally for sequencing and progress tracking.
```ts
const completion = useSlideCompletion();
completion.markPassedWithScore(90); // stores score=90, min=0, max=100 on this slide's objective
completion.score; // 90
```
- Always 0–100 range (fixed)
- Stored per-slide via `cmi.objectives`
- Not automatically aggregated into the course score
- Used for per-slide tracking, not LMS gradebook reporting
### When to use which
| Scenario | Use |
| ------------------------------------------ | -------------------------------------------------------------- |
| Quiz slides with automatic scoring | `defineTest()` — handles both slide and course score |
| Setting the overall grade manually | `scormState.score.raw = 85` |
| Tracking how a learner scored on one slide | `completion.markPassedWithScore(90)` |
| Custom grading from slide scores | Read slide scores, compute average, set `scormState.score.raw` |
---
## Course Completion vs Slide Completion
These are also two separate concepts.
### Course completion (`scormState.completion`)
The **course completion** is the overall status reported to the LMS via `cmi.core.lesson_status` (SCORM 1.2) or `cmi.completion_status` / `cmi.success_status` (SCORM 2004). This is what the LMS uses to mark the course as done.
```ts
scormState.completion.status; // 'completed' | 'incomplete' | 'not attempted' | 'unknown'
scormState.completion.success; // 'passed' | 'failed' | 'unknown'
```
| Method | Status | Success |
| ----------------- | ---------- | ------------- |
| `setCompleted()` | completed | _(unchanged)_ |
| `setIncomplete()` | incomplete | unknown |
| `setPassed()` | completed | passed |
| `setFailed()` | completed | failed |
- You call these yourself when your course logic decides the learner is done
- The LMS uses this to determine if the learner has finished
### Slide completion (`useSlideCompletion()` / `coursePlayer.getSlideStatus()`)
**Slide completion** is a per-slide status stored in SCORM objectives. It drives sequencing (which slides are locked/unlocked) and progress tracking.
```ts
// From inside a slide component:
const completion = useSlideCompletion();
completion.status; // 'passed' | 'failed' | 'incomplete' | 'not attempted'
completion.isPassed; // true if passed
completion.markPassed(); // mark this slide as passed
// From anywhere:
coursePlayer.getSlideStatus(slide); // same status values
coursePlayer.isLocked(slide); // true if previous slide not passed (linear mode)
```
- Managed automatically for `'auto'` slides (passed on visit)
- Managed via `useSlideCompletion()` for `'manual'` slides
- Not automatically aggregated into course completion
### When to use which
| Scenario | Use |
| ------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Telling the LMS the learner finished the course | `scormState.completion.setPassed()` |
| Gating navigation so slide 3 requires slide 2 to pass | Set `completionMode: 'manual'` + `useSlideCompletion()` |
| Checking if all slides are done to decide course status | Read `coursePlayer.course.slidesCompleted === coursePlayer.course.totalSlides` |
---
## Persistent Store
Key-value storage that persists in SCORM `suspend_data`.
```ts
const store = scormState.store;
```
### String / Number / Boolean / Object
```ts
store.setString('theme', 'dark');
store.getString('theme'); // 'dark' | undefined
store.setNumber('fontSize', 16);
store.getNumber('fontSize'); // 16 | undefined
store.setBoolean('soundOn', true);
store.getBoolean('soundOn'); // true | undefined
store.setObject('prefs', { a: 1 });
store.getObject<{ a: number }>('prefs'); // { a: 1 } | undefined
store.has('theme'); // true
store.delete('theme');
```
All set operations auto-persist immediately.
### Access All Variables
```ts
store.variables; // Record — reactive
```
---
## Interactions
Record learner responses to questions. Written to the SCORM `cmi.interactions` data model for LMS reporting.
```ts
store.recordInteraction({
id: 'q:lesson1:slide1:question1',
type: 'choice', // 'true-false' | 'choice' | 'fill-in' | 'matching' | etc.
learnerResponse: 'A',
correctResponse: 'B',
result: 'incorrect', // 'correct' | 'incorrect' | 'unanticipated' | 'neutral'
weighting: 1 // points
// optional: latency, objectiveId, description (2004 only)
});
```
### Reading History (current session only)
```ts
store.interactionHistory; // Record
// RecordedInteraction:
// { id, type, learnerResponse, correctResponse, result, weighting, timestamp }
```
> **Note:** `cmi.interactions` are write-only on most SCORM 1.2 LMS. History is available within a session but not across sessions. Use objectives for cross-session state.
---
## Objectives
Automatically created when you `recordInteraction()`. Persist across sessions via `cmi.objectives`.
```ts
store.isObjectivePassed('q:lesson1:slide1:question1'); // boolean
store.getObjective('q:lesson1:slide1:question1');
// { id, status: 'passed' | 'failed' | 'incomplete' | 'not attempted', score? }
```
### How it works
- When `result === 'correct'` -> objective status = `'passed'`
- When `result === 'incorrect'` -> objective status = `'failed'`
- A `'passed'` objective is never downgraded to `'failed'`
- Objective IDs should use a `q:` prefix for quiz objectives: `q:lessonId:slideId:questionId`
### Slide objectives
Slide completion state is also stored as objectives with IDs in the format `slide:{lessonId}:{slideId}`. These are managed automatically by the player — you don't need to interact with them directly.
---
## Storage Modes
Set in `defineCourse({ storageMode: ... })`:
| Mode | How | Limits | Best for |
| ---------------------- | ----------------------------------------------------- | ---------------------- | -------------------------------------- |
| `'standard'` (default) | Variables compressed in `suspend_data` | 4KB (1.2), 64KB (2004) | Most courses |
| `'chunked'` | Overflow data split across `cmi.interactions` records | Virtually unlimited | Large courses with lots of stored data |
---
## App Structure
```
src/
course.ts <- Define your course here
App.svelte <- Root component (don't edit usually)
_core/
player/
CourseShell.svelte <- Handles init, routing, lifecycle (internal)
player.svelte.ts <- coursePlayer singleton
player-metrics.svelte.ts <- Reactive metrics
slide-completion.svelte.ts <- useSlideCompletion() hook
slide-context.svelte.ts <- Slide identity context (internal)
router.svelte.ts <- sv-router setup (internal)
types.ts <- defineCourse/Lesson/Slide, type definitions
scorm/
state.svelte.ts <- scormState singleton
persistent-store.svelte.ts <- Key-value + interactions + objectives + slide tracking
score-state.svelte.ts <- Score management
completion-state.svelte.ts <- Completion management
storage/ <- Storage engines (internal)
quiz/
types.ts <- Question, TestDefinition, TestHandle interfaces
define-multi-choice.svelte.ts <- defineMultiChoiceQuestion factory
define-true-false.svelte.ts <- defineTrueFalseQuestion factory
define-test.svelte.ts <- defineTest factory
test-registry.svelte.ts <- Global test registry + course score sync
course/
layouts/
CourseFrame.svelte <- Course-level layout (sidebar + header)
LessonFrame.svelte <- Lesson-level layout (title + prev/next nav)
slides/ <- Your slide components go here
lib/
components/
app-sidebar.svelte <- Course navigation sidebar (lock/check icons)
ui/ <- shadcn-svelte components (button, sidebar, etc.)
```
### Layouts
**CourseFrame** — wraps the entire course. Provides sidebar navigation, header, progress bar.
**LessonFrame** — wraps each lesson's slides. Shows lesson title, previous/next buttons.
Both accept a `children` snippet:
```svelte
{@render children()}
```
---
## Dev vs LMS Mode
| | Dev Mode | LMS Mode |
| -------------- | --------------------------- | ------------------------------------ |
| API | localStorage | SCORM API |
| Detection | No SCORM API found | `window.API` or `window.API_1484_11` |
| Storage prefix | `scorm-dev:{courseId}:` | N/A |
| Student info | Empty strings | From LMS |
| Check | `scormState.mode === 'dev'` | `scormState.mode === 'lms'` |
Dev mode activates automatically when no LMS is detected (e.g., running `vite dev`). All data persists in the browser's localStorage.