@intellectif/lk-core 0.2.1 → 0.3.1

package/dist/activity-zdcAMtFB.d.ts

@@ -0,0 +1,626 @@
+/**
+ * Configurable free-text answer matching (R3.3).
+ *
+ * Grade-stability contract: the DEFAULTS reproduce the v1 fill-in-the-blanks
+ * semantics exactly (trim, then locale-insensitive lowercase, strict `===`).
+ * Every tolerance below is opt-in, because changing a default here changes
+ * historical grades — and this SDK powers real summative exams.
+ */
+interface TextMatchPolicy {
+    /** Compare case-sensitively. Default `false` (v1 behaviour). */
+    caseSensitive?: boolean;
+    /** Strip leading/trailing whitespace before comparing. Default `true` (v1 behaviour). */
+    trim?: boolean;
+    /**
+     * Unicode normalization applied to both sides before comparing. Default
+     * `'none'` (v1 behaviour). `'NFC'` makes a decomposed `está` (combining
+     * U+0301) equal its composed form — the fix for accent-input mismatches in
+     * EN/ES/PT content.
+     */
+    normalize?: 'none' | 'NFC' | 'NFKC';
+    /** Treat diacritics as equal to their base letters (`está` ≡ `esta`). Default `false`. */
+    foldDiacritics?: boolean;
+    /** Collapse runs of inner whitespace to a single space. Default `false`. */
+    collapseInnerWhitespace?: boolean;
+    /** Ignore Unicode punctuation on both sides. Default `false`. */
+    ignorePunctuation?: boolean;
+    /** Maximum Levenshtein edit distance still accepted as a match. Default `0`. */
+    levenshtein?: number;
+    /**
+     * BCP 47 tag for locale-aware case folding (e.g. `'tr'` for Turkish dotted /
+     * dotless I). Default: locale-insensitive `toLowerCase()` (v1 behaviour).
+     */
+    locale?: string;
+}
+/**
+ * How a match was achieved. Lets a consumer award full credit for an `exact`
+ * match and partial credit for a `folded` or `fuzzy` one (e.g. diacritic
+ * tolerance in a listening gap-fill vs. a spelling test).
+ * - `exact` — equal under the baseline trim/case rules alone.
+ * - `normalized` — required Unicode normalization, whitespace collapse, or punctuation tolerance.
+ * - `folded` — required diacritic folding.
+ * - `fuzzy` — required Levenshtein tolerance.
+ * - `none` — no accepted answer matched.
+ */
+interface TextMatchResult {
+    matched: boolean;
+    via: 'exact' | 'normalized' | 'folded' | 'fuzzy' | 'none';
+}
+/**
+ * Levenshtein distance with an early-exit bound: returns `max + 1` as soon as
+ * the distance provably exceeds `max`.
+ */
+declare function levenshteinDistance(a: string, b: string, max: number): number;
+/**
+ * Matches a learner's input against one or more accepted answers under a
+ * {@link TextMatchPolicy}. Tolerances are evaluated in stages — baseline
+ * (trim/case), then normalization, then diacritic folding, then Levenshtein —
+ * and {@link TextMatchResult.via} reports the first stage that produced the
+ * match, so graders can award credit by match quality.
+ *
+ * With no policy (or an empty one) this is byte-for-byte the v1 matching
+ * semantics: `trim` + locale-insensitive `toLowerCase` + strict equality.
+ */
+declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
+
+/**
+ * An xAPI Activity object — the thing a statement is about.
+ * This SDK only builds Activity-type objects (xAPI 1.0.3 §4.1.4.1).
+ */
+interface XAPIObject {
+    objectType: 'Activity';
+    /** IRI uniquely identifying the activity. */
+    id: string;
+    definition?: {
+        /** Language-map of human-readable names for the activity. */
+        name?: Record<string, string>;
+        /** Language-map of human-readable descriptions. */
+        description?: Record<string, string>;
+        /** IRI identifying the activity type. */
+        type?: string;
+        /** xAPI 1.0.3 cmi.interaction type (e.g. `choice`, `fill-in`, `long-fill-in`). */
+        interactionType?: string;
+        /** Patterns describing the correct response(s), per the xAPI CRP format. */
+        correctResponsesPattern?: string[];
+        /** For `choice`-family interactions: the available components. */
+        choices?: Array<{
+            id: string;
+            description?: Record<string, string>;
+        }>;
+        extensions?: Record<string, unknown>;
+    };
+}
+/**
+ * An xAPI Agent (person or system) that performed the statement's verb.
+ * Exactly one of `mbox` or `account` must be present.
+ */
+interface XAPIActor {
+    objectType: 'Agent';
+    /** Display name for the actor. */
+    name?: string;
+    /** Mailto IRI uniquely identifying the actor (e.g. `mailto:user@example.com`). */
+    mbox?: string;
+    /** Account-based actor identifier. */
+    account?: {
+        /** IRI of the home page of the account's service provider. */
+        homePage: string;
+        /** The actor's unique name on that service. */
+        name: string;
+    };
+}
+/** An xAPI Verb — the action performed in the statement. */
+interface XAPIVerbObject {
+    /** IRI uniquely identifying this verb (e.g. from adlnet.gov/expapi/verbs). */
+    id: string;
+    /** Language-map of human-readable verb labels. */
+    display: Record<string, string>;
+}
+/** Score sub-object within an xAPI Result. */
+interface XAPIScore {
+    /** Normalized score in the range [0, 1]. */
+    scaled: number;
+    /** Raw score in the instrument's native scale. */
+    raw?: number;
+    /** Minimum possible raw score. */
+    min?: number;
+    /** Maximum possible raw score. */
+    max?: number;
+}
+/** Result information attached to an xAPI Statement. */
+interface XAPIResult {
+    score?: XAPIScore;
+    /** Whether the actor's performance was successful. */
+    success?: boolean;
+    /** Whether the activity was completed. */
+    completion?: boolean;
+    /** ISO 8601 duration string representing time spent (e.g. `PT5M30S`). */
+    duration?: string;
+    /** A string representation of the learner's response. */
+    response?: string;
+    extensions?: Record<string, unknown>;
+}
+/** Related-activity references attached to a statement's context. */
+interface XAPIContextActivities {
+    /** Activities this statement's activity is directly part of (e.g. the exam section). */
+    parent?: XAPIObject[];
+    /** Broader groupings (e.g. the course). */
+    grouping?: XAPIObject[];
+    /** Categorisations (e.g. a profile IRI). */
+    category?: XAPIObject[];
+    /** Other contextually related activities. */
+    other?: XAPIObject[];
+}
+/** Context information attached to an xAPI Statement. */
+interface XAPIContext {
+    /** Name of the software used to record the statement. */
+    platform?: string;
+    /** BCP 47 language tag for the activity content. */
+    language?: string;
+    /** Related activities (parent/grouping/category/other). */
+    contextActivities?: XAPIContextActivities;
+    extensions?: Record<string, unknown>;
+}
+/** A complete xAPI 1.0.3 Statement. */
+interface XAPIStatement {
+    /** UUID v4 uniquely identifying this statement. */
+    id: string;
+    actor: XAPIActor;
+    verb: XAPIVerbObject;
+    object: XAPIObject;
+    result?: XAPIResult;
+    context?: XAPIContext;
+    /** ISO 8601 timestamp of when the statement occurred. */
+    timestamp: string;
+    version: '1.0.3';
+}
+/**
+ * Configuration passed to `useXAPI` to connect to an LRS endpoint.
+ * The `auth` field supports both HTTP Basic and Bearer token authentication.
+ */
+interface XAPIConfig {
+    /** Full URL of the LRS statements endpoint. */
+    endpoint: string;
+    /** Authentication credentials for the LRS. */
+    auth: {
+        type: 'basic';
+        username: string;
+        password: string;
+    } | {
+        type: 'bearer';
+        token: string;
+    };
+    /**
+     * Replaces the SDK's placeholder object id (`urn:learning-kit:activity:*`)
+     * before a statement is sent.
+     *
+     * - `string` — the IRI for THE activity this hook instance serves. A hook
+     *   instance is per-activity by contract; with several activities sharing
+     *   one hook, a plain string would collapse their statements onto one IRI —
+     *   use the function form instead.
+     * - `(sdkObjectId) => string` — maps each placeholder id (which embeds the
+     *   activity's `data.id`) to its deployment IRI, for pages that send many
+     *   activities through one hook.
+     *
+     * Object ids the consumer already rewrote (non-`urn:learning-kit:` ids) are
+     * never touched.
+     */
+    activityId: string | ((sdkObjectId: string) => string);
+    actor: XAPIActor;
+    /** Called after all retry attempts are exhausted. */
+    onError?: (err: XAPIError) => void;
+}
+/** Error payload delivered to `XAPIConfig.onError` after retries are exhausted. */
+interface XAPIError {
+    /** The statement that failed to send. */
+    statement: XAPIStatement;
+    /** The 1-based attempt number on which the final failure occurred. */
+    attempt: number;
+    /** HTTP status code from the LRS, if a response was received. */
+    statusCode?: number;
+    /** Human-readable error description. */
+    message: string;
+}
+
+/**
+ * Maps each ActivityType string to its corresponding data shape.
+ *
+ * Open for extension via TypeScript module augmentation: a consumer that
+ * registers a custom activity type (`registerActivityType`) can augment this
+ * interface so `ActivityType`, `ActivityData`, `validateActivity`, and
+ * `evaluate` pick the new type up without an SDK release:
+ *
+ * ```ts
+ * declare module '@intellectif/lk-core' {
+ *   interface ActivityDataMap { 'my-type': MyTypeData }
+ *   interface LearnerResponseMap { 'my-type': MyTypeLearnerResponse }
+ * }
+ * ```
+ */
+interface ActivityDataMap {
+    'multiple-choice': MultipleChoiceData;
+    'fill-in-the-blanks': FillInTheBlanksData;
+    'written-response': WrittenResponseData;
+}
+/**
+ * The set of activity types supported by learning-kit. Derived from
+ * {@link ActivityDataMap}, so module augmentation widens it automatically.
+ */
+type ActivityType = keyof ActivityDataMap;
+/** Union of all valid activity data shapes. */
+type ActivityData = ActivityDataMap[ActivityType];
+/**
+ * Optional media (image/audio/video) shown above a question or passage.
+ * URL-only: hosting/delivery is the consuming application's responsibility.
+ */
+interface ActivityMedia {
+    /** The kind of media; selects the rendered element. `embed` → sandboxed iframe. */
+    type: 'image' | 'audio' | 'video' | 'embed';
+    /**
+     * Source URL. For `embed` this MUST be the provider's embeddable URL
+     * (e.g. `https://www.youtube.com/embed/<id>`), not the watch page.
+     */
+    url: string;
+    /** Alternative text. Required for `image` and `embed`; optional label for audio/video. */
+    alt?: string;
+    /** Optional WebVTT captions track URL for `audio`/`video`. */
+    captionsUrl?: string;
+}
+/**
+ * Optional authored "overall feedback" shown after submission, chosen by
+ * whether the learner passed (h5p-style overall feedback). Distinct from
+ * per-option feedback; either field may be omitted.
+ */
+interface ActivityFeedback {
+    /** Shown when the learner passes (score ≥ pass threshold). */
+    correct?: string;
+    /** Shown when the learner does not pass. */
+    incorrect?: string;
+}
+/** A single selectable option within a Multiple Choice activity. */
+interface MultipleChoiceOption {
+    /** Unique identifier for this option within the activity. */
+    id: string;
+    /** Display text shown to the learner. */
+    text: string;
+    /** Whether this option is part of the correct answer. */
+    isCorrect: boolean;
+    /** Optional per-option feedback shown after submission. */
+    feedback?: string;
+}
+/** Data contract for a Multiple Choice activity. */
+interface MultipleChoiceData {
+    schemaVersion: '1.0';
+    type: 'multiple-choice';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** The question stem presented to the learner, as plain text. */
+    question: string;
+    /**
+     * Optional sanitised rich-HTML rendering of the question, parallel to
+     * `WrittenResponseData.promptHtml`. The SDK carries and redacts it as
+     * learner-visible content but does not render it yet (components escape
+     * text); sanitisation is the application's responsibility.
+     */
+    questionHtml?: string;
+    /** `single` allows one selection; `multi` allows multiple. */
+    mode: 'single' | 'multi';
+    /** Ordered list of answer options. */
+    options: MultipleChoiceOption[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the question. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+    passThreshold?: number;
+    /** When true, options are shuffled deterministically per session. */
+    shuffle?: boolean;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** Configuration for a single fill-in-the-blank slot. */
+interface BlankConfig {
+    /** Unique identifier matching the `{{blank_id}}` placeholder in the passage. */
+    id: string;
+    /** List of strings accepted as correct answers for this blank. */
+    acceptedAnswers: string[];
+    /** Whether answer matching is case-sensitive. Defaults to false. */
+    caseSensitive?: boolean;
+    /** Whether leading/trailing whitespace is stripped before matching. Defaults to true. */
+    trimWhitespace?: boolean;
+    /**
+     * Optional matching-tolerance policy for this blank (Unicode normalization,
+     * diacritic folding, whitespace collapse, punctuation tolerance, typo
+     * tolerance). Every tolerance is opt-in; when absent, matching reproduces
+     * the v1 trim + case-fold semantics exactly. Fields set here take
+     * precedence over the legacy `caseSensitive` / `trimWhitespace` flags.
+     */
+    match?: TextMatchPolicy;
+    /** Optional hint text revealed on learner request. */
+    hint?: string;
+    /** Optional feedback shown inline next to this blank after submission. */
+    feedback?: string;
+}
+/** Data contract for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksData {
+    schemaVersion: '1.0';
+    type: 'fill-in-the-blanks';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** Passage text containing `{{blank_id}}` placeholders. */
+    passage: string;
+    /**
+     * Optional sanitised rich-HTML rendering of the passage, parallel to
+     * `WrittenResponseData.promptHtml`. Carried and redacted as learner-visible
+     * content; not rendered by the SDK yet. Sanitisation is the application's.
+     */
+    passageHtml?: string;
+    /** Configuration for each blank in the passage. */
+    blanks: BlankConfig[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the passage. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** A single criterion within a written-response grading rubric. */
+interface WrittenResponseRubricCriterion {
+    /** Criterion name (e.g. "Task achievement", "Grammar range"). */
+    name: string;
+    /** Optional longer description of what the criterion assesses. */
+    description?: string;
+    /** Non-negative weight of this criterion in the overall grade. */
+    weight: number;
+}
+/** Grading rubric attached to a written-response activity. */
+interface WrittenResponseRubric {
+    /** Optional display label for the rubric as a whole. */
+    label?: string;
+    /** The criteria the response is graded against. Non-empty when present. */
+    criteria: WrittenResponseRubricCriterion[];
+}
+/**
+ * Data contract for a Written Response activity (free-text writing graded
+ * asynchronously — by an AI or human grader — after submission).
+ *
+ * Wire-format note (Req 22.9): field names and casing are locked for
+ * byte-compatibility with consumer-stored JSONB rows. `feedback` and
+ * `passThreshold` are SDK-side optional additions for component parity
+ * (Req 22.8 / Req 3.9) — being optional, their absence keeps stored payloads
+ * byte-identical.
+ */
+interface WrittenResponseData {
+    schemaVersion: '1.0';
+    type: 'written-response';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** The writing prompt, as plain text. */
+    prompt: string;
+    /** Optional sanitised rich-HTML sidecar of the prompt (not rendered by the SDK yet). */
+    promptHtml?: string;
+    /** Minimum acceptable word count (≥ 0). */
+    minWords: number;
+    /** Maximum acceptable word count (≥ 1, and ≥ `minWords`). */
+    maxWords: number;
+    /** Optional grading rubric consumed by the asynchronous grader. */
+    rubric?: WrittenResponseRubric;
+    /** Optional target language/level for the response (e.g. `"en-A2"`, `"es-B1"`). */
+    languageTarget?: string;
+    /** Optional media shown above the prompt. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback (surfaced once the deferred grade exists). */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass once graded. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/**
+ * Maps each ActivityType string to its learner-response shape. Open for
+ * extension via module augmentation, mirroring {@link ActivityDataMap}.
+ */
+interface LearnerResponseMap {
+    'multiple-choice': MultipleChoiceLearnerResponse;
+    'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
+    'written-response': WrittenResponseLearnerResponse;
+}
+/** Union of all learner response shapes. */
+type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
+/** Learner response for a Multiple Choice activity. */
+interface MultipleChoiceLearnerResponse {
+    type: 'multiple-choice';
+    /** IDs of the options the learner selected. */
+    selectedOptionIds: string[];
+}
+/** Learner response for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksLearnerResponse {
+    type: 'fill-in-the-blanks';
+    /** Map of blank ID to the learner's typed answer. */
+    answers: Record<string, string>;
+}
+/** Learner response for a Written Response activity. */
+interface WrittenResponseLearnerResponse {
+    type: 'written-response';
+    /** The learner's free-text response. */
+    text: string;
+    /** Word count of `text`, computed with the canonical `countWords()` helper. */
+    wordCount: number;
+}
+/**
+ * Fine-grained outcome of the learner's action on a single item, replacing the
+ * ambiguous {@link ScoringDetail.correct}:
+ * - `correct` — the learner selected/entered the right answer.
+ * - `incorrect` — the learner selected/entered a wrong answer.
+ * - `correct-omission` — the learner correctly left a non-answer unselected (multiple-choice only).
+ * - `incorrect-omission` — the learner failed to select a correct answer (multiple-choice only).
+ */
+type ScoringOutcome = 'correct' | 'incorrect' | 'correct-omission' | 'incorrect-omission';
+/** Per-item scoring breakdown returned by the scoring engine. */
+interface ScoringDetail {
+    /** ID of the option or blank this detail refers to. */
+    itemId: string;
+    /**
+     * @deprecated Ambiguous: for multiple-choice this means "the learner acted
+     * correctly on this option" (`wasSelected === option.isCorrect`), NOT "this
+     * option is the answer" — an unselected wrong option reads `correct: true`.
+     * Read {@link ScoringDetail.outcome} instead; `correct` remains written for
+     * backward compatibility and will be removed in v1.0.
+     */
+    correct: boolean;
+    /**
+     * Unambiguous outcome of the learner's action on this item. Optional in the
+     * type so 0.2-era consumer-constructed literals keep compiling, but ALWAYS
+     * written by both built-in scorers since 0.3.0; becomes required in v1.0
+     * when the deprecated `correct` is removed.
+     */
+    outcome?: ScoringOutcome;
+    /** The learner's actual response for this item. */
+    learnerResponse: string | string[];
+    /** The expected correct response(s) for this item. */
+    correctResponse: string | string[];
+    /**
+     * Weight applied to this item's contribution to the overall score. Both
+     * built-in scorers currently weight every item equally and write `1`.
+     */
+    weight?: number;
+}
+/** Full scoring result returned by the scoring engine. */
+interface ScoringResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the score meets or exceeds the activity's pass threshold. */
+    passed: boolean;
+    /**
+     * The authored overall feedback selected for this result: `feedback.correct`
+     * when the learner passed, `feedback.incorrect` otherwise; `null` when the
+     * activity authored no matching feedback.
+     */
+    feedback: string | null;
+    /** Per-item scoring breakdown. */
+    details: ScoringDetail[];
+}
+/**
+ * Progress facts about a deferred (asynchronously graded) submission that are
+ * computable synchronously at submit time. For written-response, both fields
+ * are always present and `wordCount` is recomputed from the submitted text
+ * with the canonical `countWords()` (the client-supplied count is not trusted).
+ */
+interface DeferredScoringPartial {
+    /** Whether the recomputed word count falls within `[minWords, maxWords]`. */
+    withinWordBounds?: boolean;
+    /** Recomputed word count of the submitted text. */
+    wordCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * The outcome of evaluating a learner response against an activity — the
+ * union `evaluate()` returns. Unlike {@link ScoringResult}, it can express
+ * "not gradable yet" (`deferred`) and "not gradable at all" (`unscorable`),
+ * so an ungraded written response is never conflated with a score of 0.
+ */
+type ItemOutcome = {
+    status: 'scored';
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score. */
+    maxScore: number;
+    /** Whether the score meets or exceeds the activity's pass threshold. */
+    passed: boolean;
+    /** Authored overall feedback selected by pass state, or null. */
+    feedback: string | null;
+    /** Per-item scoring breakdown. */
+    details: ScoringDetail[];
+} | {
+    status: 'deferred';
+    /** Why the grade is deferred (asynchronous AI/human grading). */
+    reason: 'requires_async_grading';
+    /** Maximum possible scaled score once graded. */
+    maxScore: number;
+    /** Synchronously computable progress facts (word bounds, counts). */
+    partial?: DeferredScoringPartial;
+} | {
+    status: 'unscorable';
+    /** Why no grade can be produced (e.g. unregistered activity type). */
+    reason: string;
+    /** Maximum possible scaled score, when known. */
+    maxScore: number;
+};
+/** A single validation error produced by `validateActivity`. */
+interface ValidationError {
+    /** JSON-path-style location of the invalid field. */
+    path: string[];
+    /** Human-readable description of the validation failure. */
+    message: string;
+    /** Machine-readable error code. */
+    code: string;
+}
+/**
+ * Result of a `validateActivity` call.
+ * On success, `data` is the validated and typed activity data.
+ * On failure, `errors` contains one entry per violated constraint.
+ */
+type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: ValidationError[];
+};
+/** The payload delivered to an activity's `onComplete` callback. */
+interface ActivityResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the learner passed based on the activity's pass threshold. */
+    passed: boolean;
+    /** Time in milliseconds from first interaction to submission. */
+    timeSpent: number;
+    /** The xAPI statement built and (optionally) sent for this attempt. */
+    xapiStatement: XAPIStatement;
+}
+/**
+ * The kinds of interaction the built-in components emit. Custom activity types
+ * registered by consumers may emit their own kinds, so any string is accepted;
+ * the named literals are kept for autocompletion.
+ */
+type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled' | 'hint-requested' | 'text-changed' | 'submitted' | (string & {});
+/** Fired by activity components on every discrete learner interaction. */
+interface InteractionEvent {
+    /** The kind of interaction that occurred. */
+    type: InteractionKind;
+    /** ID of the activity that produced the event. */
+    activityId: string;
+    /** Unix timestamp (ms) of when the interaction occurred. */
+    timestamp: number;
+    /** Additional event-specific data. */
+    payload: Record<string, unknown>;
+}
+
+export { type ActivityData as A, type BlankConfig as B, type XAPIVerbObject as C, type DeferredScoringPartial as D, levenshteinDistance as E, type FillInTheBlanksData as F, matchText as G, type InteractionEvent as I, type LearnerResponse as L, type MultipleChoiceData as M, type ScoringDetail as S, type TextMatchPolicy as T, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type ActivityDataMap as a, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type InteractionKind as g, type ItemOutcome as h, type LearnerResponseMap as i, type MultipleChoiceLearnerResponse as j, type MultipleChoiceOption as k, type ScoringOutcome as l, type ScoringResult as m, type TextMatchResult as n, type ValidationResult as o, type WrittenResponseLearnerResponse as p, type WrittenResponseRubric as q, type WrittenResponseRubricCriterion as r, type XAPIConfig as s, type XAPIContext as t, type XAPIContextActivities as u, type XAPIError as v, type XAPIObject as w, type XAPIResult as x, type XAPIScore as y, type XAPIStatement as z };

package/dist/chunk-3YAVDV5F.js

@@ -0,0 +1,47 @@
+// src/errors.ts
+var ActivitySchemaError = class extends Error {
+  constructor(activityType, errors) {
+    super(`Invalid activity data for type "${activityType}"`);
+    this.activityType = activityType;
+    this.errors = errors;
+    this.name = "ActivitySchemaError";
+  }
+  activityType;
+  errors;
+};
+var UnknownActivityTypeError = class extends Error {
+  constructor(activityType) {
+    super(`Activity type "${activityType}" is not registered`);
+    this.activityType = activityType;
+    this.name = "UnknownActivityTypeError";
+  }
+  activityType;
+};
+var RedactedScoringError = class extends Error {
+  constructor(activityType) {
+    super(
+      `Activity data for "${activityType}" carries no answer key (it looks redacted), so it cannot be scored. Score against the full activity data server-side, or use evaluate() which returns { status: "unscorable" }.`
+    );
+    this.activityType = activityType;
+    this.name = "RedactedScoringError";
+  }
+  activityType;
+};
+var DeferredScoringError = class extends Error {
+  constructor(activityType) {
+    super(
+      `Activity type "${activityType}" is graded asynchronously and has no synchronous score. Use evaluate() \u2014 it returns { status: 'deferred' } for this type.`
+    );
+    this.activityType = activityType;
+    this.name = "DeferredScoringError";
+  }
+  activityType;
+};
+
+export {
+  ActivitySchemaError,
+  UnknownActivityTypeError,
+  RedactedScoringError,
+  DeferredScoringError
+};
+//# sourceMappingURL=chunk-3YAVDV5F.js.map

package/dist/chunk-3YAVDV5F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["import type { ValidationError } from './types/activity.js';\n\n/** Thrown when activity data fails schema validation at a component boundary. */\nexport class ActivitySchemaError extends Error {\n  constructor(\n    public readonly activityType: string,\n    public readonly errors: ValidationError[],\n  ) {\n    super(`Invalid activity data for type \"${activityType}\"`);\n    this.name = 'ActivitySchemaError';\n  }\n}\n\n/** Thrown when an unrecognised activity type is passed to the scoring engine. */\nexport class UnknownActivityTypeError extends Error {\n  constructor(public readonly activityType: string) {\n    super(`Activity type \"${activityType}\" is not registered`);\n    this.name = 'UnknownActivityTypeError';\n  }\n}\n\n/**\n * Thrown when `score()` is asked to grade a `redact()` projection (or any\n * activity data whose answer key is missing, yielding a non-finite score).\n * Redacted data is learner-safe precisely because the key was removed, so a\n * score derived from it is meaningless — previously this produced a silent\n * `NaN` that serialized to `null` in a grade column. `evaluate()` returns\n * `{ status: 'unscorable' }` for the same input instead of throwing.\n */\nexport class RedactedScoringError extends Error {\n  constructor(public readonly activityType: string) {\n    super(\n      `Activity data for \"${activityType}\" carries no answer key (it looks redacted), so it cannot be scored. ` +\n        'Score against the full activity data server-side, or use evaluate() which returns { status: \"unscorable\" }.',\n    );\n    this.name = 'RedactedScoringError';\n  }\n}\n\n/**\n * Thrown when `score()` is called for an activity type whose grading is\n * deferred (asynchronous AI/human grading, e.g. `written-response`). A\n * deferred submission has no synchronous score — treating it as 0 would show\n * a learner a failing grade for work that simply has not been graded yet.\n * Call `evaluate()` instead, which returns `{ status: 'deferred', ... }`.\n */\nexport class DeferredScoringError extends Error {\n  constructor(public readonly activityType: string) {\n    super(\n      `Activity type \"${activityType}\" is graded asynchronously and has no synchronous score. ` +\n        `Use evaluate() — it returns { status: 'deferred' } for this type.`,\n    );\n    this.name = 'DeferredScoringError';\n  }\n}\n"],"mappings":";AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC7C,YACkB,cACA,QAChB;AACA,UAAM,mCAAmC,YAAY,GAAG;AAHxC;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AAAA,EALkB;AAAA,EACA;AAKpB;AAGO,IAAM,2BAAN,cAAuC,MAAM;AAAA,EAClD,YAA4B,cAAsB;AAChD,UAAM,kBAAkB,YAAY,qBAAqB;AAD/B;AAE1B,SAAK,OAAO;AAAA,EACd;AAAA,EAH4B;AAI9B;AAUO,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAA4B,cAAsB;AAChD;AAAA,MACE,sBAAsB,YAAY;AAAA,IAEpC;AAJ0B;AAK1B,SAAK,OAAO;AAAA,EACd;AAAA,EAN4B;AAO9B;AASO,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAA4B,cAAsB;AAChD;AAAA,MACE,kBAAkB,YAAY;AAAA,IAEhC;AAJ0B;AAK1B,SAAK,OAAO;AAAA,EACd;AAAA,EAN4B;AAO9B;","names":[]}