@conform-ed/qti-react 0.0.12 → 0.0.14

package/dist/rp/evaluate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shared QTI expression evaluator (ADR-0004), used by both response processing and
+ * template processing. The environment supplies variable lookup, declarations, and —
+ * only where the spec allows nondeterminism (template processing) — a seeded PRNG.
+ * Random operators without a PRNG in the environment are unsupported constructs:
+ * response processing must stay deterministic and replayable.
+ */
+import type { ResponseDeclarationView, ResponseValue } from "../types";
+import type { CustomOperatorImplementation, ResponseNormalization, RpExpressionView } from "./types";
+import { type MaybeRpValue } from "./values";
+export interface EvalEnv {
+    readonly lookupVariable: (identifier: string) => MaybeRpValue;
+    readonly responseDeclaration: (identifier: string) => ResponseDeclarationView | undefined;
+    readonly responseValue: (identifier: string) => ResponseValue;
+    readonly normalization?: ResponseNormalization | undefined;
+    /** Seeded PRNG in [0, 1); present only in template processing. */
+    readonly random?: (() => number) | undefined;
+    /** `testVariables` aggregation; present only in test-level outcome processing. */
+    readonly testVariables?: (expression: RpExpressionView) => MaybeRpValue;
+    /** The `number*` item-session aggregates; present only in test-level outcome processing. */
+    readonly testAggregate?: (expression: RpExpressionView) => MaybeRpValue;
+    /** Registered vendor operators by class; unregistered classes stay unsupported. */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
+}
+/** Expression kinds legal everywhere (deterministic). */
+export declare const deterministicExpressionKinds: ReadonlySet<string>;
+/** Expression kinds requiring the seeded PRNG (template processing only). */
+export declare const randomExpressionKinds: ReadonlySet<string>;
+export declare class RpUnsupportedError extends Error {
+    readonly kindName: string;
+    constructor(kindName: string);
+}
+export declare function evaluateExpression(expression: RpExpressionView, env: EvalEnv): MaybeRpValue;
+/** Walk an expression tree, reporting kinds outside the allowed set. */
+export declare function collectExpressionIssues(expression: RpExpressionView, allowedKinds: ReadonlySet<string>, report: (name: string) => void, customOperatorClasses?: ReadonlySet<string>): void;

package/dist/rp/index.d.ts

@@ -0,0 +1,4 @@
+export { collectRpIssues, executeResponseProcessing } from "./interpreter";
+export { applyCorrectResponseOverrides, collectTemplateIssues, executeTemplateProcessing, mulberry32, type TemplateConditionBranch, type TemplateProcessingContext, type TemplateProcessingResult, type TemplateProcessingView, type TemplateRuleView, } from "./template-processing";
+export { resolveTemplate } from "./templates";
+export type { CustomOperatorImplementation, MaybeRpValue, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingContext, ResponseProcessingResult, ResponseProcessingView, RpConditionBranch, RpExpressionView, RpRecordField, RpRuleView, RpScalar, RpValue, TemplateDeclarationView, } from "./types";

package/dist/rp/interpreter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Response Processing Interpreter (ADR-0004): a pure, deterministic evaluator of
+ * the contracts-validated `responseProcessing` tree. Operator coverage grows milestone
+ * by milestone; anything outside it aborts execution to the declared outcome defaults
+ * and is reported as an `unsupported-rp` Capability issue — never partial scoring.
+ */
+import type { CapabilityIssue } from "../capability";
+import type { ResponseProcessingContext, ResponseProcessingResult, ResponseProcessingView } from "./types";
+export declare function executeResponseProcessing(view: ResponseProcessingView | undefined, context: ResponseProcessingContext): ResponseProcessingResult;
+export interface RpIssueOptions {
+    /** `customOperator` classes the consumer has registered implementations for. */
+    readonly customOperatorClasses?: ReadonlySet<string>;
+}
+/** Static coverage walk for `canDeliver`: reports constructs the interpreter lacks without executing. */
+export declare function collectRpIssues(view: ResponseProcessingView | undefined, options?: RpIssueOptions): readonly CapabilityIssue[];

package/dist/rp/template-processing.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Template processing (ADR-0004): the seeded, deterministic engine that produces an
+ * item clone. Given the same seed, the same template values and correctResponse
+ * overrides come out — replayability survives randomized items because the seed, not
+ * the outcome, is what gets stored. Supported rules: setTemplateValue,
+ * templateCondition, setCorrectResponse, exitTemplate.
+ */
+import type { CapabilityIssue } from "../capability";
+import type { CorrectResponseView, ResponseDeclarationView } from "../types";
+import type { CustomOperatorImplementation, OutcomeValue, RpExpressionView, TemplateDeclarationView } from "./types";
+export interface TemplateConditionBranch {
+    readonly expression: RpExpressionView;
+    readonly rules: readonly TemplateRuleView[];
+}
+export interface TemplateRuleView {
+    readonly kind: string;
+    readonly identifier?: string;
+    readonly expression?: RpExpressionView;
+    readonly templateIf?: TemplateConditionBranch;
+    readonly templateElseIfs?: readonly TemplateConditionBranch[];
+    readonly templateElse?: {
+        readonly rules: readonly TemplateRuleView[];
+    };
+}
+export interface TemplateProcessingView {
+    readonly rules: readonly TemplateRuleView[];
+}
+export interface TemplateProcessingContext {
+    readonly templateDeclarations: readonly TemplateDeclarationView[];
+    readonly responseDeclarations: readonly ResponseDeclarationView[];
+    readonly seed: number;
+    /** Registered vendor `customOperator` implementations by class (opt-in). */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
+}
+export interface TemplateProcessingResult {
+    readonly templateValues: Readonly<Record<string, OutcomeValue>>;
+    /** correctResponse values set by setCorrectResponse, keyed by response identifier. */
+    readonly correctResponseOverrides: Readonly<Record<string, CorrectResponseView>>;
+    readonly issues: readonly CapabilityIssue[];
+}
+/** mulberry32: a tiny, fast, seeded PRNG — deterministic across platforms. */
+export declare function mulberry32(seed: number): () => number;
+export declare function executeTemplateProcessing(view: TemplateProcessingView | undefined, context: TemplateProcessingContext): TemplateProcessingResult;
+/** The effective response declarations for a clone: setCorrectResponse overrides applied. */
+export declare function applyCorrectResponseOverrides(declarations: readonly ResponseDeclarationView[], overrides: Readonly<Record<string, CorrectResponseView>>): readonly ResponseDeclarationView[];
+/** Static coverage walk for `canDeliver` over a templateProcessing tree. */
+export declare function collectTemplateIssues(view: TemplateProcessingView | undefined, options?: {
+    readonly customOperatorClasses?: ReadonlySet<string>;
+}): readonly CapabilityIssue[];

package/dist/rp/templates.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The QTI standard response-processing templates as built-in canonical rule trees
+ * (ADR-0004): templates are interpreter inputs, not a separate scoring path. URIs are
+ * matched by their final path segment, so both the QTI 2.x and 3.0 purl forms resolve.
+ */
+import type { RpRuleView } from "./types";
+/** Resolve a standard-template URI to its canonical rules, or null when unknown. */
+export declare function resolveTemplate(uri: string): readonly RpRuleView[] | null;

package/dist/rp/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Structural views of QTI 3 `responseProcessing` and `outcomeDeclaration` (ADR-0004).
+ * Like the rest of the runtime's views, these are narrowed shapes of the
+ * `@conform-ed/contracts` schemas: validation happens upstream, the interpreter works
+ * against these types and reports anything it does not understand via the Capability
+ * Report instead of guessing.
+ */
+import type { CapabilityIssue } from "../capability";
+import type { Cardinality, ResponseDeclarationView, ResponseValue } from "../types";
+export type RpScalar = string | number | boolean;
+/** An outcome variable's value as exposed to consumers after response processing. */
+export type OutcomeValue = RpScalar | readonly RpScalar[] | null;
+/** One named member of a record-cardinality value (QTI record containers). */
+export interface RpRecordField {
+    readonly name: string;
+    readonly baseType?: string;
+    readonly value: RpScalar;
+}
+/** The interpreter's typed value model: (baseType, cardinality, members); NULL is null. */
+export interface RpValue {
+    readonly cardinality: Cardinality;
+    readonly baseType?: string;
+    readonly values: readonly RpScalar[];
+    /** Present only when cardinality is "record"; `values` mirrors the field values. */
+    readonly fields?: readonly RpRecordField[];
+}
+export type MaybeRpValue = RpValue | null;
+export interface OutcomeDeclarationView {
+    readonly identifier: string;
+    readonly cardinality: Cardinality;
+    readonly baseType?: string;
+    readonly defaultValue?: {
+        readonly values: ReadonlyArray<{
+            readonly value: RpScalar;
+        }>;
+    };
+}
+/**
+ * One expression node. Deliberately loose (`kind: string`): kinds the interpreter
+ * does not implement yet flow through and surface as `unsupported-rp` issues.
+ */
+export interface RpExpressionView {
+    readonly kind: string;
+    readonly identifier?: string;
+    readonly baseType?: string;
+    readonly value?: RpScalar;
+    readonly expressions?: readonly RpExpressionView[];
+    /** Bounds/step for the random operators (template processing). */
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    /** `equal` tolerance window; string entries are template references (unsupported). */
+    readonly toleranceMode?: "exact" | "absolute" | "relative";
+    readonly tolerance?: ReadonlyArray<number | string>;
+    readonly includeLowerBound?: boolean;
+    readonly includeUpperBound?: boolean;
+    /** 1-based position for `index`. */
+    readonly n?: number | string;
+    /** Function/constant name for `mathOperator`, `mathConstant`, `statsOperator`. */
+    readonly name?: string;
+    /** Rounding controls for `roundTo` and `equalRounded`. */
+    readonly roundingMode?: "decimalPlaces" | "significantFigures";
+    readonly figures?: number | string;
+    /** Pass count for `repeat`. */
+    readonly numberRepeats?: number | string;
+    /** String comparison controls for `stringMatch` and `substring`. */
+    readonly caseSensitive?: boolean;
+    readonly substring?: boolean;
+    /** Area for `inside` (QTI shape + coords string). */
+    readonly shape?: string;
+    readonly coords?: string;
+    /** Test-level subset selection (`testVariables` and the `number*` aggregates). */
+    readonly variableIdentifier?: string;
+    readonly weightIdentifier?: string;
+    readonly sectionIdentifier?: string;
+    readonly includeCategory?: string | readonly string[];
+    readonly excludeCategory?: string | readonly string[];
+    /** Vendor identification for `customOperator` (implementation registered by class). */
+    readonly class?: string;
+    readonly definition?: string;
+    /** Named-field selector for `fieldValue` over record-cardinality values. */
+    readonly fieldIdentifier?: string;
+}
+/**
+ * A consumer-registered `customOperator` implementation, keyed by its `class`
+ * attribute. Receives the already-evaluated child values; returns NULL-or-value like
+ * any expression. Vendor operators are by definition engine-specific (the spec leaves
+ * them implementation-defined), so nothing ships registered — same opt-in stance as
+ * PCI modules.
+ */
+export type CustomOperatorImplementation = (args: readonly MaybeRpValue[], expression: RpExpressionView) => MaybeRpValue;
+export interface RpConditionBranch {
+    readonly expression: RpExpressionView;
+    readonly rules: readonly RpRuleView[];
+}
+/** One response rule: responseCondition, setOutcomeValue, or exitResponse. */
+export interface RpRuleView {
+    readonly kind: string;
+    readonly identifier?: string;
+    readonly expression?: RpExpressionView;
+    readonly responseIf?: RpConditionBranch;
+    readonly responseElseIfs?: readonly RpConditionBranch[];
+    readonly responseElse?: {
+        readonly rules: readonly RpRuleView[];
+    };
+}
+/** Either a standard-template URI or an explicit rule tree (rules win if both). */
+export interface ResponseProcessingView {
+    readonly template?: string;
+    readonly rules?: readonly RpRuleView[];
+}
+/**
+ * Response Normalization (ADR-0004): an opt-in, consumer-configured transform of
+ * candidate string input applied at comparison time. Off by default; always off in
+ * conformance runs. Applied to both sides of string comparisons so keys and candidate
+ * input normalize identically.
+ */
+export type ResponseNormalization = (value: string, declaration?: ResponseDeclarationView) => string;
+export interface TemplateDeclarationView {
+    readonly identifier: string;
+    readonly cardinality: Cardinality;
+    readonly baseType?: string;
+    readonly defaultValue?: {
+        readonly values: ReadonlyArray<{
+            readonly value: RpScalar;
+        }>;
+    };
+}
+/**
+ * Consumer-supplied input. Optional members deliberately admit explicit
+ * `undefined` ("undefined means not provided"): callers pass maybe-undefined
+ * values straight through, and the interpreter reads every member field-wise
+ * (`??`/`?.`) — option bags are never spread-merged over defaults.
+ */
+export interface ResponseProcessingContext {
+    readonly responseDeclarations: readonly ResponseDeclarationView[];
+    readonly outcomeDeclarations: readonly OutcomeDeclarationView[];
+    readonly responses: Readonly<Record<string, ResponseValue>>;
+    readonly normalization?: ResponseNormalization | undefined;
+    /** Template variables for this clone (read by `variable` lookups). */
+    readonly templateDeclarations?: readonly TemplateDeclarationView[] | undefined;
+    readonly templateValues?: Readonly<Record<string, OutcomeValue>> | undefined;
+    /** Adaptive carry-over: outcome values from earlier attempts replace declared defaults. */
+    readonly priorOutcomes?: Readonly<Record<string, OutcomeValue>> | undefined;
+    /**
+     * Random source for `random`/`randomInteger`/`randomFloat` in RP (adaptive items,
+     * e.g. Monty Hall door reveals). Seed it from the attempt seed: the seed plus the
+     * submission sequence then replays the exact same outcomes (ADR-0004 determinism).
+     */
+    readonly random?: (() => number) | undefined;
+    /** Registered vendor `customOperator` implementations by class (opt-in). */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
+}
+export interface ResponseProcessingResult {
+    readonly outcomes: Readonly<Record<string, OutcomeValue>>;
+    /** Non-empty means execution aborted to declared defaults (never partial scoring). */
+    readonly issues: readonly CapabilityIssue[];
+}

package/dist/rp/values.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The interpreter's typed value model. QTI runtime values are (baseType, cardinality,
+ * members); NULL is represented as `null`. Comparison is baseType-aware: pairs are
+ * unordered within the pair, directedPairs ordered, strings normalize through the
+ * consumer's Response Normalization hook (identity by default), numbers compare
+ * numerically.
+ */
+import type { Cardinality, ResponseDeclarationView, ResponseValue } from "../types";
+import type { MaybeRpValue, OutcomeValue, ResponseNormalization, RpScalar, RpValue } from "./types";
+export type { MaybeRpValue, RpValue } from "./types";
+export declare function isNumericBaseType(baseType: string | undefined): boolean;
+/** Coerce a raw scalar to its declared baseType (numbers and booleans may arrive as strings). */
+export declare function coerceScalar(value: RpScalar, baseType: string | undefined): RpScalar;
+/** Lift a store ResponseValue into the typed model using its declaration. */
+export declare function fromResponse(declaration: ResponseDeclarationView, response: ResponseValue): MaybeRpValue;
+export declare function singleNumber(value: MaybeRpValue): number | null;
+export declare function singleBoolean(value: MaybeRpValue): boolean | null;
+/** Construct a typed value; an unknown baseType is omitted, never stored as undefined. */
+export declare function rpValue(cardinality: Cardinality, values: readonly RpScalar[], baseType?: string): RpValue;
+export declare function booleanValue(value: boolean): RpValue;
+export declare function floatValue(value: number): RpValue;
+export declare function scalarsEqual(a: RpScalar, b: RpScalar, baseType: string | undefined, normalize?: ResponseNormalization): boolean;
+/** QTI `match`: same cardinality; ordered compares sequences, containers compare multisets. */
+export declare function valuesMatch(a: RpValue, b: RpValue, normalize?: ResponseNormalization): boolean;
+/** Rebuild a typed value from a flattened OutcomeValue (templates, adaptive carry-over). */
+export declare function fromFlatValue(value: OutcomeValue, cardinality: Cardinality, baseType?: string): MaybeRpValue;
+export declare function toOutcomeValue(value: MaybeRpValue): OutcomeValue;

package/dist/runtime.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The headless runtime (ADR-0001): a factory that assembles a QTI item renderer from an
+ * injected set of interaction descriptors plus a skin registry. The kind-union is the
+ * injected set — no global registry, no module augmentation. The core owns response
+ * state and a11y wiring; skins are controlled components.
+ *
+ * No Mantine, and no JSX — flow content and skins are composed with `createElement` so
+ * the package needs no JSX build step.
+ */
+import { type ComponentType, type ReactNode } from "react";
+import type { ZodType } from "zod";
+import type { CapabilityReport } from "./capability";
+import { type ContentModel } from "./content-model";
+import type { CustomOperatorImplementation, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingView, TemplateDeclarationView, TemplateProcessingView } from "./rp";
+import { type AttemptSnapshot, type AttemptStore } from "./store";
+import type { ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+export type { CapabilityIssue, CapabilityIssueType, CapabilityReport } from "./capability";
+export interface XmlContentNode {
+    kind: "xml";
+    name: string;
+    value?: string;
+    attributes?: Record<string, unknown>;
+    children?: BodyNode[];
+}
+export interface InteractionNode {
+    kind: string;
+    responseIdentifier: string;
+    [field: string]: unknown;
+}
+export type BodyNode = XmlContentNode | InteractionNode | {
+    kind: string;
+    value?: string;
+    children?: BodyNode[];
+};
+/** A feedback element's view: feedbackInline/feedbackBlock in the body, or modalFeedback. */
+export interface FeedbackView {
+    outcomeIdentifier: string;
+    identifier: string;
+    showHide?: "show" | "hide";
+    content?: readonly BodyNode[];
+}
+export interface AssessmentItemView {
+    responseDeclarations: readonly ResponseDeclarationView[];
+    outcomeDeclarations?: readonly OutcomeDeclarationView[];
+    responseProcessing?: ResponseProcessingView;
+    templateDeclarations?: readonly TemplateDeclarationView[];
+    templateProcessing?: TemplateProcessingView;
+    /** QTI adaptive item: multiple attempts until completionStatus reaches "completed". */
+    adaptive?: boolean;
+    modalFeedbacks?: readonly FeedbackView[];
+    itemBody: {
+        content?: BodyNode[];
+    };
+}
+export interface InteractionDescriptor<Kind extends string = string> {
+    readonly kind: Kind;
+    readonly schema: ZodType;
+    readonly scoring: "qti-standard";
+    /** The empty/initial response for a fresh attempt at this interaction. */
+    initialResponse(node: InteractionNode): ResponseValue;
+}
+export declare function defineInteraction<Kind extends string>(descriptor: InteractionDescriptor<Kind>): InteractionDescriptor<Kind>;
+export type OptionStatus = "idle" | "selected" | "correct" | "incorrect";
+/** Whole-interaction status (for interactions without options, e.g. textEntry). */
+export type InteractionStatus = "unanswered" | "answered" | "correct" | "incorrect";
+/** Prop-getter result a skin spreads onto an option element to inherit selection + a11y. */
+export interface OptionProps {
+    role: "radio" | "checkbox";
+    tabIndex: number;
+    "aria-checked": boolean;
+    "aria-disabled": boolean;
+    "data-status": OptionStatus;
+    onClick: () => void;
+}
+/** Controlled props every interaction skin receives by default (ADR-0001). */
+export interface InteractionRenderProps {
+    node: InteractionNode;
+    responseIdentifier: string;
+    value: ResponseValue;
+    setValue: (value: ResponseValue) => void;
+    /** True after submit — the interaction is read-only. */
+    disabled: boolean;
+    /** True after submit — show correct/incorrect chrome. */
+    showFeedback: boolean;
+    /** Whole-interaction status (drives feedback for option-less interactions). */
+    status: InteractionStatus;
+    getOptionProps: (optionIdentifier: string) => OptionProps;
+    /**
+     * Render body fragments (prompt, choice labels) through the core allowlist walk.
+     * `overrides` lets a skin take over specific node kinds nested anywhere in the
+     * fragment (e.g. `hottext`, `gap`) while the core keeps walking everything else.
+     */
+    renderContent: (nodes: readonly BodyNode[] | undefined, overrides?: NodeOverrides) => ReactNode;
+    /** The runtime's Asset Resolver (identity when none configured) for skin-owned media. */
+    resolveAsset: (href: string) => string;
+    /** Set this interaction's response to true and submit the attempt (endAttemptInteraction). */
+    endAttempt: () => void;
+    /**
+     * Register a submit-time response collector for this interaction (imperative
+     * interactions like PCI own their response state). Returns the unregister function.
+     */
+    registerResponseCollector: (collector: () => ResponseValue | undefined) => () => void;
+}
+/** Per-kind render overrides a skin passes to `renderContent` for nodes it owns. */
+export type NodeOverrides = Readonly<Record<string, (node: BodyNode, key: number) => ReactNode>>;
+export type InteractionSkin = ComponentType<InteractionRenderProps>;
+export type SkinRegistry = Readonly<Record<string, InteractionSkin>>;
+export interface QtiRuntimeConfig {
+    readonly interactions: readonly InteractionDescriptor[];
+    readonly skin: SkinRegistry;
+    readonly contentModel?: ContentModel;
+    /** Replaces the default Unsupported Placeholder for interaction nodes this runtime cannot render. */
+    readonly renderUnsupported?: (node: InteractionNode) => ReactNode;
+    /** The Response Normalization hook (ADR-0004): opt-in candidate-input leniency. */
+    readonly normalization?: ResponseNormalization;
+    /**
+     * The Asset Resolver: maps package-relative media references (img/audio/video `src`,
+     * `poster`) to real URLs at render time. Identity when omitted.
+     */
+    readonly assetResolver?: (href: string) => string;
+    /**
+     * Registered vendor `customOperator` implementations by class. Items using only
+     * registered classes pass the capability gate; everything else stays unsupported.
+     */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+}
+export interface ItemRendererProps {
+    item: AssessmentItemView;
+    /**
+     * An externally owned attempt store. Without it the renderer creates a fresh
+     * per-mount store; passing one enables review/replay modes (rehydrate a stored,
+     * already-submitted attempt) and server-side rendering of submitted states.
+     */
+    store?: AttemptStore | undefined;
+    /** Clone seed for template processing; store it to replay the same clone. */
+    seed?: number | undefined;
+    children?: ReactNode;
+}
+export interface ContentRendererProps {
+    nodes?: readonly BodyNode[] | undefined;
+    /** Values for printedVariable (and showHide-gated feedback) inside the content. */
+    outcomes?: Readonly<Record<string, OutcomeValue>> | undefined;
+}
+export interface QtiRuntime {
+    ItemRenderer: ComponentType<ItemRendererProps>;
+    /**
+     * Flow content outside an item attempt — test feedback, rubric copy. Same sanitizer
+     * and node walk as the item body, over caller-supplied outcome values.
+     */
+    ContentRenderer: ComponentType<ContentRendererProps>;
+    useAttempt: () => AttemptController;
+    /**
+     * The Capability Report for an item against this runtime's injected descriptors,
+     * skins, and content model. Consumers gate delivery on it (ADR-0003); the
+     * ItemRenderer placeholder is only the backstop for content that reaches
+     * rendering anyway.
+     */
+    canDeliver: (item: AssessmentItemView) => CapabilityReport;
+}
+export interface AttemptController extends AttemptSnapshot {
+    submit: () => readonly ScoreResult[];
+    reset: () => void;
+}
+export declare function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime;

package/dist/store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The response store the headless core owns (ADR-0001): it holds candidate responses
+ * keyed by `responseIdentifier`, the submitted flag, and the scored outcomes. Skins are
+ * controlled against it; they never own response state (only ephemeral UI state).
+ *
+ * Backed by an external store so `useSyncExternalStore` can subscribe with narrow,
+ * snapshot-stable reads. No React import here — the hook lives in the runtime.
+ *
+ * Template processing runs once at store creation under the given seed (ADR-0004):
+ * the seed is the replay key for a randomized clone. Adaptive items (`adaptive`)
+ * support multiple attempts: outcomes carry over between RP runs and the item locks
+ * only when `completionStatus` reaches "completed".
+ */
+import type { CustomOperatorImplementation, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingView, TemplateDeclarationView, TemplateProcessingView } from "./rp";
+import type { ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+export interface AttemptSnapshot {
+    readonly responses: Readonly<Record<string, ResponseValue>>;
+    readonly submitted: boolean;
+    /** Per-response heuristic results backing the per-interaction feedback chrome. */
+    readonly scores: readonly ScoreResult[];
+    /** Item outcomes of record from the RP interpreter; empty before submit or without RP. */
+    readonly outcomes: Readonly<Record<string, OutcomeValue>>;
+    /** This clone's template variables (empty without templateProcessing). */
+    readonly templateValues: Readonly<Record<string, OutcomeValue>>;
+    /** Completed attempts so far (only ever exceeds 1 for adaptive items). */
+    readonly attemptCount: number;
+}
+/**
+ * Consumer-supplied input. Optional members deliberately admit explicit
+ * `undefined` ("undefined means not provided"), so callers can pass
+ * maybe-undefined values straight through; the store reads every member
+ * field-wise (`??`/`?.`) and never spread-merges options over defaults.
+ */
+export interface AttemptStoreOptions {
+    readonly outcomeDeclarations?: readonly OutcomeDeclarationView[] | undefined;
+    readonly responseProcessing?: ResponseProcessingView | undefined;
+    /** The Response Normalization hook (ADR-0004); applies to scores and outcomes alike. */
+    readonly normalization?: ResponseNormalization | undefined;
+    readonly templateDeclarations?: readonly TemplateDeclarationView[] | undefined;
+    readonly templateProcessing?: TemplateProcessingView | undefined;
+    /** Clone seed for template processing; store it to replay the same clone. */
+    readonly seed?: number | undefined;
+    /** QTI adaptive item: multiple attempts, outcome carry-over, completionStatus lock. */
+    readonly adaptive?: boolean | undefined;
+    /** Registered vendor `customOperator` implementations by class (opt-in). */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
+}
+export interface AttemptStore {
+    readonly getSnapshot: () => AttemptSnapshot;
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly setResponse: (responseIdentifier: string, value: ResponseValue) => void;
+    /**
+     * Imperative interactions (PCI) hold their response internally; a collector pulls it
+     * at submit time, before scoring. Returning undefined leaves the response unchanged.
+     * Returns the unregister function.
+     */
+    readonly registerResponseCollector: (responseIdentifier: string, collector: () => ResponseValue | undefined) => () => void;
+    readonly submit: () => readonly ScoreResult[];
+    readonly reset: () => void;
+}
+export declare function createAttemptStore(declarations: readonly ResponseDeclarationView[], initialResponses: Readonly<Record<string, ResponseValue>>, options?: AttemptStoreOptions): AttemptStore;

package/dist/test/controller.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The headless Test Controller (ADR-0005): given an assessmentTest view and a seed, it
+ * resolves the delivery plan (seeded selection + ordering) once, then answers every
+ * navigation, branching, and outcome-processing question as a pure transition over the
+ * consumer-persisted session state. It owns no storage and renders nothing.
+ */
+import type { AssessmentTestView, TestController } from "./types";
+export interface TestControllerOptions {
+    readonly seed: number;
+}
+export declare function createTestController(view: AssessmentTestView, options: TestControllerOptions): TestController;

package/dist/test/index.d.ts

@@ -0,0 +1,3 @@
+export { createTestController, type TestControllerOptions } from "./controller";
+export { createTestSessionStore, type TestSessionSnapshot, type TestSessionStore, type TestSessionStoreOptions, } from "./session-store";
+export type { AssessmentItemRefView, AssessmentSectionView, AssessmentTestView, BranchRuleView, ItemSessionControlView, OutcomeConditionBranch, OutcomeRuleView, TestController, TestFeedbackView, TestItemResult, TestPartView, TestPlan, TestPlanItem, TestPlanPart, TestSessionState, TimeLimitsView, } from "./types";

package/dist/test/session-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The Test Session Store: glue between the headless Test Controller (ADR-0005) and
+ * per-item Attempt Stores. It holds the controller's JSON session state, creates item
+ * stores lazily with key-derived seeds (so every clone is replayable from the test
+ * seed alone), and feeds item submissions back into the controller so test outcome
+ * processing stays current. React-free — UI layers subscribe like any external store;
+ * persistence stays with the consumer (store the seed and `snapshot.state`).
+ */
+import type { CustomOperatorImplementation, ResponseNormalization } from "../rp";
+import type { AssessmentItemView } from "../runtime";
+import { type AttemptStore } from "../store";
+import type { AssessmentItemRefView, TestController, TestFeedbackView, TestPlanItem, TestSessionState } from "./types";
+export interface TestSessionStoreOptions {
+    /**
+     * Resolve an item ref to its view. Synchronous by design: load the package's items
+     * before mounting the session; return null for refs that cannot be delivered.
+     */
+    readonly resolveItem: (ref: AssessmentItemRefView) => AssessmentItemView | null;
+    /** The test seed: drives plan resolution replay and derives per-item clone seeds. */
+    readonly seed: number;
+    /** Resume a persisted session (item responses are session-local, not part of it). */
+    readonly initialState?: TestSessionState;
+    readonly normalization?: ResponseNormalization;
+    /** Registered vendor `customOperator` implementations by class (opt-in). */
+    readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+}
+export interface TestSessionSnapshot {
+    readonly state: TestSessionState;
+    readonly currentItem: TestPlanItem | null;
+    /** The resolved view for the current item, or null when unresolvable. */
+    readonly currentItemView: AssessmentItemView | null;
+    readonly visibleFeedbacks: readonly TestFeedbackView[];
+}
+export interface TestSessionStore {
+    readonly controller: TestController;
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly getSnapshot: () => TestSessionSnapshot;
+    /** The item's Attempt Store — created once per key, reused across navigation. */
+    readonly itemStore: (itemKey: string) => AttemptStore | null;
+    readonly itemView: (itemKey: string) => AssessmentItemView | null;
+    readonly next: () => void;
+    readonly canMoveTo: (itemKey: string) => boolean;
+    readonly moveTo: (itemKey: string) => void;
+    readonly end: () => void;
+}
+export declare function createTestSessionStore(controller: TestController, options: TestSessionStoreOptions): TestSessionStore;