@conform-ed/qti-react 0.0.14 → 0.0.16

package/dist/normalized-item.d.ts

@@ -11,18 +11,20 @@
  * - `gapChoices` split into the runtime's `gapTexts` (gapMatch) / `gapImgs` (graphic)
  * - media/upload/positionObjectStage flatten to the descriptor fields
  * - processing trees: `children` → `expressions`, `actions` → `rules`,
- *   `responseElseIf`/`templateElseIf` pluralize
+ *   `responseElseIf`/`templateElseIf` pluralize; fragment rules keep their
+ *   nested `rules` verbatim
  *
  * Used by the corpus delivery meter (ADR-0002) and by any consumer ingesting
  * normalized XML.
  */
-import type { AssessmentItemView } from "./runtime";
+import type { AssessmentItemView, StimulusContentView } from "./runtime";
 import type { AssessmentTestView } from "./test";
+export declare function assessmentItemViewFromNormalized(document: unknown): AssessmentItemView | null;
 /**
- * Reshape a normalized QTI document (the `normalizedDocument` from qti-xml validation)
- * into an `AssessmentItemView`, or null when it is not an assessment item.
+ * The renderable body of a normalized AssessmentStimulus document, for
+ * `QtiRuntimeConfig.resolveStimulus`. Returns null for non-stimulus documents.
  */
-export declare function assessmentItemViewFromNormalized(document: unknown): AssessmentItemView | null;
+export declare function stimulusContentFromNormalized(document: unknown): StimulusContentView | null;
 /**
  * Reshape a normalized QTI document into the Test Controller's `AssessmentTestView`,
  * or null when it is not an assessment test.

package/dist/pnp.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AfA PNP (QTI 3.0 profile) views and catalog support resolution.
+ *
+ * The catalog holds "support-specific dormant content that can be made active … based
+ * on the candidate's PNP information (or an assessment program's settings)" (§5.28).
+ * This module owns the two halves of that sentence: which supports are active for a
+ * candidate (activation), and which card content realises an active support
+ * (matching). Rendering is the runtime's job; time-limit adjustments are the test
+ * controller's.
+ *
+ * Views are structural mirrors of the contracts AfA PNP and catalog schemas — the
+ * package depends on contracts only in tests, like the rest of qti-react.
+ */
+import type { BodyNode } from "./runtime";
+export interface PnpReplaceAccessModeView {
+    readonly replaceAccessModes?: readonly string[];
+}
+export interface PnpLanguageModeView extends PnpReplaceAccessModeView {
+    readonly xmlLang: string;
+}
+/** additional-testing-time: "Only one of the available options can be selected." */
+export interface PnpAdditionalTestingTimeView extends PnpReplaceAccessModeView {
+    readonly timeMultiplier?: number;
+    readonly fixedMinutes?: number;
+    readonly unlimited?: boolean;
+}
+export interface PnpFeatureSetView {
+    readonly features?: readonly string[];
+}
+/**
+ * The candidate's preferences, shaped like the normalized access-for-all-pnp
+ * document. Feature preference objects carry the fields card-entry discriminators
+ * match against (xmlLang, readingType, …); unknown fields are preserved.
+ */
+export interface PnpView {
+    readonly [feature: string]: unknown;
+    readonly languageOfInterface?: readonly PnpLanguageModeView[];
+    readonly keywordTranslation?: PnpLanguageModeView;
+    readonly itemTranslation?: PnpLanguageModeView;
+    readonly signLanguage?: PnpLanguageModeView;
+    readonly additionalTestingTime?: PnpAdditionalTestingTimeView;
+    readonly activateAtInitializationSet?: PnpFeatureSetView;
+    readonly activateAsOptionSet?: PnpFeatureSetView;
+    readonly prohibitSet?: PnpFeatureSetView;
+}
+export interface CatalogFileHrefView {
+    readonly href: string;
+    readonly mimeType: string;
+}
+export interface CatalogContentView {
+    readonly xmlLang?: string;
+    readonly dataAttributes?: Readonly<Record<string, string>>;
+    readonly content?: readonly BodyNode[];
+}
+export interface CatalogCardEntryView {
+    readonly xmlLang?: string;
+    readonly default?: boolean;
+    readonly dataAttributes?: Readonly<Record<string, string>>;
+    readonly htmlContent?: CatalogContentView;
+    readonly fileHrefs?: readonly CatalogFileHrefView[];
+}
+export interface CatalogCardView {
+    readonly support: string;
+    readonly xmlLang?: string;
+    readonly htmlContent?: CatalogContentView;
+    readonly fileHrefs?: readonly CatalogFileHrefView[];
+    readonly cardEntries?: readonly CatalogCardEntryView[];
+}
+export interface CatalogView {
+    readonly id: string;
+    readonly cards: readonly CatalogCardView[];
+}
+export interface PnpActivation {
+    /** Supports in effect from the start of the session. */
+    readonly active: ReadonlySet<string>;
+    /** Supports the candidate may turn on during the session (activate-as-option-set). */
+    readonly optional: ReadonlySet<string>;
+    /** Supports that must not be offered (prohibit-set) — wins over everything. */
+    readonly prohibited: ReadonlySet<string>;
+}
+/**
+ * Resolve the activation policy: prohibit-set wins; activate-at-initialization-set is
+ * active; activate-as-option-set is offered but off. A preference stated outside any
+ * set (e.g. a bare keyword-translation) is honored from the start — the PNP records
+ * the need, and without an activation policy there is nothing to defer to (designed
+ * policy, see the ADR).
+ */
+export declare function resolvePnpActivation(pnp: PnpView | undefined): PnpActivation;
+/**
+ * The PNP preference object stated for a feature — what card entries discriminate
+ * against, and what results reporting reads detail (language, time values) from.
+ */
+export declare function pnpFeaturePreference(pnp: PnpView | undefined, feature: string): Record<string, unknown> | undefined;
+/** A support's resolved alternative content for one catalog. */
+export interface ResolvedCatalogSupport {
+    readonly support: string;
+    readonly xmlLang?: string;
+    readonly content?: readonly BodyNode[];
+    readonly fileHrefs?: readonly CatalogFileHrefView[];
+}
+export interface CatalogResolution {
+    readonly activation: PnpActivation;
+    readonly byCatalogId: ReadonlyMap<string, readonly ResolvedCatalogSupport[]>;
+}
+/**
+ * Resolve every catalog's active alternative content for a candidate. `activeSupports`
+ * is the delivery-engine channel — program settings and candidate-toggled options
+ * ("or an assessment program's settings", §5.28); prohibited supports stay out even
+ * when named there.
+ */
+export declare function resolveCatalogSupports(options: {
+    readonly catalogs?: readonly CatalogView[] | undefined;
+    readonly pnp?: PnpView | undefined;
+    readonly activeSupports?: readonly string[] | undefined;
+}): CatalogResolution;

package/dist/response-validity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Response validity (ItemSessionControl validate-responses): "An invalid response is
+ * defined to be a response which does not satisfy the constraints imposed by the
+ * interaction with which it is associated." The constraint vocabulary is what the
+ * view model carries on interaction nodes — min/max-choices, min/max-associations,
+ * min-strings, pattern-mask, min-plays. Only authored attributes are validated:
+ * rendering defaults (e.g. a radio group's single choice) are interaction behavior,
+ * not submission constraints.
+ */
+import type { BodyNode } from "./runtime";
+import type { ResponseValue } from "./types";
+export type ResponseConstraintKind = "minChoices" | "maxChoices" | "minAssociations" | "maxAssociations" | "minStrings" | "patternMask" | "minPlays";
+export interface InteractionConstraint {
+    readonly responseIdentifier: string;
+    readonly kind: ResponseConstraintKind;
+    /** The declared bound: a count for the min/max constraints, the XSD regex for patternMask. */
+    readonly bound: number | string;
+}
+/** A constraint the current response fails — the reason a submission is invalid. */
+export type ResponseViolation = InteractionConstraint;
+/**
+ * Walk the item body and collect the constraint attributes its interactions carry.
+ * Zero bounds impose nothing: "If max-choices is 0 then there is no restriction";
+ * "If min-choices is 0 then the candidate is not required to select any choices."
+ */
+export declare function collectInteractionConstraints(content: readonly BodyNode[] | undefined): InteractionConstraint[];
+/** The constraints the current responses fail; empty means the responses are valid. */
+export declare function collectResponseViolations(constraints: readonly InteractionConstraint[], responses: Readonly<Record<string, ResponseValue>>): ResponseViolation[];

package/dist/rp/evaluate.d.ts

@@ -17,8 +17,13 @@ export interface EvalEnv {
     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. */
+    /**
+     * The test-level subset aggregates (`number*`, `outcomeMinimum`/`outcomeMaximum`);
+     * present only in test-level outcome processing.
+     */
     readonly testAggregate?: (expression: RpExpressionView) => MaybeRpValue;
+    /** Declared default of any item variable, for the `default` expression (§2.11.1.3). */
+    readonly variableDefault?: (identifier: string) => MaybeRpValue;
     /** Registered vendor operators by class; unregistered classes stay unsupported. */
     readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }

package/dist/rp/index.d.ts

@@ -1,4 +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 { applyCorrectResponseOverrides, applyTemplateDefaultOverrides, 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";
+export type { CustomOperatorImplementation, InterpolationTableEntryView, InterpolationTableView, MatchTableEntryView, MatchTableView, MaybeRpValue, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingContext, ResponseProcessingResult, ResponseProcessingView, RpConditionBranch, RpExpressionView, RpRecordField, RpRuleView, RpScalar, RpValue, TemplateDeclarationView, } from "./types";

package/dist/rp/interpreter.d.ts

@@ -5,11 +5,17 @@
  * and is reported as an `unsupported-rp` Capability issue — never partial scoring.
  */
 import type { CapabilityIssue } from "../capability";
-import type { ResponseProcessingContext, ResponseProcessingResult, ResponseProcessingView } from "./types";
+import type { OutcomeDeclarationView, 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>;
+    /**
+     * The item's outcome declarations; when supplied, a `lookupOutcomeValue` rule whose
+     * declaration carries no lookupTable is reported statically (gate parity with the
+     * runtime refusal).
+     */
+    readonly outcomeDeclarations?: readonly OutcomeDeclarationView[];
 }
 /** 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/lookup-table.d.ts

@@ -0,0 +1,17 @@
+/**
+ * lookupTable evaluation for the `lookupOutcomeValue` rule (§5.87): "sets the value
+ * of an outcome variable to the value obtained by looking up the value of the
+ * associated expression in the lookupTable associated with the outcome's
+ * declaration." Shared by the item interpreter and the test controller — the test's
+ * own outcome declarations use the same view type.
+ */
+import type { OutcomeDeclarationView } from "./types";
+import { type MaybeRpValue } from "./values";
+export declare function hasLookupTable(declaration: OutcomeDeclarationView | undefined): declaration is OutcomeDeclarationView;
+/**
+ * Look `source` up in the declaration's lookupTable. A NULL or non-numeric source is
+ * read as "no matching table entry is found" (§5.90.1) — an interpretive call the
+ * spec leaves open — so it takes the defaultValue path, never a refusal. "If
+ * omitted, the NULL value is used." (§5.90.1/§5.78.1)
+ */
+export declare function lookupTableValue(declaration: OutcomeDeclarationView, source: MaybeRpValue): MaybeRpValue;

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

@@ -41,6 +41,11 @@ export interface TemplateProcessingResult {
 /** 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 template declarations for a clone: test-level `templateDefault`
+ * values (§5.152) replace the declared defaults. A NULL value clears the default.
+ */
+export declare function applyTemplateDefaultOverrides(declarations: readonly TemplateDeclarationView[], overrides: Readonly<Record<string, OutcomeValue>>): readonly TemplateDeclarationView[];
 /** 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. */

package/dist/rp/types.d.ts

@@ -25,6 +25,38 @@ export interface RpValue {
     readonly fields?: readonly RpRecordField[];
 }
 export type MaybeRpValue = RpValue | null;
+/** One matchTable row: exact integer source → target (§7.23). */
+export interface MatchTableEntryView {
+    readonly sourceValue: number;
+    readonly targetValue: RpScalar;
+}
+/**
+ * "A matchTable transforms a source integer by finding the first
+ * qti-match-table-entry with an exact match to the source." (§5.90)
+ */
+export interface MatchTableView {
+    /** "The default outcome value to be used when no matching table entry is found.
+     * If omitted, the NULL value is used." (§5.90.1) */
+    readonly defaultValue?: RpScalar;
+    readonly matchTableEntries: readonly MatchTableEntryView[];
+}
+/** One interpolationTable row; sourceValue is "the lower bound … to match this entry" (§7.18.1). */
+export interface InterpolationTableEntryView {
+    readonly sourceValue: number;
+    readonly targetValue: RpScalar;
+    /** "If 'true', the default, then an exact match of the value is considered a match
+     * of this entry." (§7.18.2) */
+    readonly includeBoundary?: boolean;
+}
+/**
+ * "An interpolationTable transforms a source float (or integer) by finding the first
+ * interpolationTableEntry with a sourceValue that is less than or equal to (subject
+ * to includeBoundary) the source value." (§5.78)
+ */
+export interface InterpolationTableView {
+    readonly defaultValue?: RpScalar;
+    readonly interpolationTableEntries: readonly InterpolationTableEntryView[];
+}
 export interface OutcomeDeclarationView {
     readonly identifier: string;
     readonly cardinality: Cardinality;
@@ -34,6 +66,12 @@ export interface OutcomeDeclarationView {
             readonly value: RpScalar;
         }>;
     };
+    /** The declaration's lookupTable (at most one of the two), read by `lookupOutcomeValue` (§5.87). */
+    readonly matchTable?: MatchTableView;
+    readonly interpolationTable?: InterpolationTableView;
+    /** Declared score bounds, aggregated by `outcomeMaximum`/`outcomeMinimum` (§2.11.2.6-7). */
+    readonly normalMaximum?: number;
+    readonly normalMinimum?: number;
 }
 /**
  * One expression node. Deliberately loose (`kind: string`): kinds the interpreter
@@ -45,11 +83,14 @@ export interface RpExpressionView {
     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). */
+    /**
+     * Bounds/step for the random operators and `anyN`; string values are variable
+     * references resolved at runtime (§2.11.3.6), bare or brace-enclosed (§7.13).
+     */
+    readonly min?: number | string;
+    readonly max?: number | string;
+    readonly step?: number | string;
+    /** `equal` tolerance window; string entries are variable references. */
     readonly toleranceMode?: "exact" | "absolute" | "relative";
     readonly tolerance?: ReadonlyArray<number | string>;
     readonly includeLowerBound?: boolean;
@@ -63,14 +104,18 @@ export interface RpExpressionView {
     readonly figures?: number | string;
     /** Pass count for `repeat`. */
     readonly numberRepeats?: number | string;
+    /** XSD-dialect pattern for `patternMatch`; "{ref}" resolves from a variable (§7.13). */
+    readonly pattern?: 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). */
+    /** Test-level subset selection (`testVariables`, `outcomeMinimum`/`outcomeMaximum`, `number*`). */
     readonly variableIdentifier?: string;
+    /** Outcome variable whose declared bounds `outcomeMinimum`/`outcomeMaximum` look up (§7.28.4). */
+    readonly outcomeIdentifier?: string;
     readonly weightIdentifier?: string;
     readonly sectionIdentifier?: string;
     readonly includeCategory?: string | readonly string[];
@@ -93,11 +138,16 @@ export interface RpConditionBranch {
     readonly expression: RpExpressionView;
     readonly rules: readonly RpRuleView[];
 }
-/** One response rule: responseCondition, setOutcomeValue, or exitResponse. */
+/**
+ * One response rule: responseCondition, setOutcomeValue, lookupOutcomeValue,
+ * responseProcessingFragment, or exitResponse.
+ */
 export interface RpRuleView {
     readonly kind: string;
     readonly identifier?: string;
     readonly expression?: RpExpressionView;
+    /** Nested rules of a `responseProcessingFragment` (§5.118). */
+    readonly rules?: readonly RpRuleView[];
     readonly responseIf?: RpConditionBranch;
     readonly responseElseIfs?: readonly RpConditionBranch[];
     readonly responseElse?: {
@@ -148,6 +198,20 @@ export interface ResponseProcessingContext {
      * submission sequence then replays the exact same outcomes (ADR-0004 determinism).
      */
     readonly random?: (() => number) | undefined;
+    /**
+     * Built-in session variables (reserved identifiers; items must not declare them).
+     * `duration` is the item session's elapsed seconds; `numAttempts` "increases by 1
+     * at the start of each attempt", so it includes the attempt being scored.
+     */
+    readonly duration?: number | undefined;
+    readonly numAttempts?: number | undefined;
+    /**
+     * The session's current `completionStatus` — the third built-in, "declared
+     * implicitly"; it enters the outcome map (defaulting to "not_attempted") so
+     * `setOutcomeValue` can change it (§2.2.2.3). An explicit declaration (legacy
+     * content) wins over this value.
+     */
+    readonly completionStatus?: string | undefined;
     /** Registered vendor `customOperator` implementations by class (opt-in). */
     readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }

package/dist/runtime.d.ts

@@ -11,12 +11,15 @@ 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 CatalogView, type PnpView, type ResolvedCatalogSupport } from "./pnp";
 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";
+    /** XML namespace URI; foreign vocabularies (SSML) are recognized by it. */
+    namespace?: string;
     name: string;
     value?: string;
     attributes?: Record<string, unknown>;
@@ -39,6 +42,31 @@ export interface FeedbackView {
     showHide?: "show" | "hide";
     content?: readonly BodyNode[];
 }
+/** An item's reference to a shared AssessmentStimulus document (§7.6). */
+export interface AssessmentStimulusRefView {
+    readonly identifier: string;
+    readonly href: string;
+    readonly title?: string;
+}
+/** Companion materials, structurally as normalized (calculators, rules, protractors, materials). */
+export interface CompanionMaterialsView {
+    readonly calculators?: readonly Record<string, unknown>[];
+    readonly rules?: readonly Record<string, unknown>[];
+    readonly protractors?: readonly Record<string, unknown>[];
+    readonly digitalMaterials?: readonly {
+        readonly fileHref: string;
+        readonly label?: string;
+        readonly mimeType?: string;
+        readonly resourceIcon?: string;
+    }[];
+    readonly physicalMaterials?: readonly string[];
+}
+/** The resolved stimulus body, rendered through the same content walk as the item body. */
+export interface StimulusContentView {
+    readonly content: readonly BodyNode[];
+    /** The stimulus document's catalogs (dormant alternative content, §5.29). */
+    readonly catalogs?: readonly CatalogView[];
+}
 export interface AssessmentItemView {
     responseDeclarations: readonly ResponseDeclarationView[];
     outcomeDeclarations?: readonly OutcomeDeclarationView[];
@@ -48,6 +76,15 @@ export interface AssessmentItemView {
     /** QTI adaptive item: multiple attempts until completionStatus reaches "completed". */
     adaptive?: boolean;
     modalFeedbacks?: readonly FeedbackView[];
+    assessmentStimulusRefs?: readonly AssessmentStimulusRefView[];
+    /** Every catalog in the item (item-level and nested), pooled for idref resolution. */
+    catalogs?: readonly CatalogView[];
+    /**
+     * Companion materials (§2.13.1): "content props that provide key information to be
+     * used when answering an Item, e.g. a calculator, protractor, lookup chart". The
+     * runtime exposes them; the delivery platform owns the tools themselves.
+     */
+    companionMaterials?: CompanionMaterialsView;
     itemBody: {
         content?: BodyNode[];
     };
@@ -100,6 +137,12 @@ export interface InteractionRenderProps {
      * interactions like PCI own their response state). Returns the unregister function.
      */
     registerResponseCollector: (collector: () => ResponseValue | undefined) => () => void;
+    /**
+     * Render the active catalog supports for a skin-owned node's data-catalog-idref
+     * (e.g. a choice label) — the same resolution and presentation the core walk
+     * applies to generic flow nodes. Null when nothing is active.
+     */
+    renderCatalogSupports: (catalogIdref: string | undefined) => ReactNode;
 }
 /** Per-kind render overrides a skin passes to `renderContent` for nodes it owns. */
 export type NodeOverrides = Readonly<Record<string, (node: BodyNode, key: number) => ReactNode>>;
@@ -123,6 +166,19 @@ export interface QtiRuntimeConfig {
      * registered classes pass the capability gate; everything else stays unsupported.
      */
     readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+    /**
+     * Resolve an item's shared-stimulus reference to its normalized body content
+     * (synchronous by design, like the session store's resolveItem: load the package's
+     * stimuli before mounting; `stimulusContentFromNormalized` reshapes a normalized
+     * document). Unresolved refs are capability issues, never silent drops (ADR-0003).
+     */
+    readonly resolveStimulus?: (ref: AssessmentStimulusRefView) => StimulusContentView | null;
+    /**
+     * Replaces the default rendering of an active catalog support (the note-role span
+     * appended beside the referenced content). The delivery engine owns presentation —
+     * tooltips, players, glossary panels — the runtime owns resolution.
+     */
+    readonly renderCatalogSupport?: (support: ResolvedCatalogSupport, catalogIdref: string) => ReactNode;
 }
 export interface ItemRendererProps {
     item: AssessmentItemView;
@@ -134,12 +190,42 @@ export interface ItemRendererProps {
     store?: AttemptStore | undefined;
     /** Clone seed for template processing; store it to replay the same clone. */
     seed?: number | undefined;
+    /**
+     * The item-session state to render. `review` is read-only: "the candidate can
+     * review the qti-item-body along with the responses they gave, but cannot update
+     * or resubmit them". `solution` additionally swaps in the clone's resolved correct
+     * responses ("a way of entering the solution state"); the show-solution gate is
+     * the consumer's (effective ItemSessionControl). Default: "interact".
+     */
+    mode?: ItemRenderMode | undefined;
+    /**
+     * Effective ItemSessionControl show-feedback; consulted only outside `interact`.
+     * `false` withholds modal and integrated feedback — visibility is then
+     * "determined by the default values of the outcome variables" — and is ignored
+     * for adaptive items, per spec.
+     */
+    showFeedback?: boolean | undefined;
+    /**
+     * The candidate's AfA PNP. Activates the item's dormant catalog supports (§5.29):
+     * "A candidate's profile (or assessment program settings) will indicate whether the
+     * candidate should be presented any of the possible supports."
+     */
+    pnp?: PnpView | undefined;
+    /**
+     * Supports in effect beyond the PNP's initial activation — program settings and
+     * candidate-toggled options (activate-as-option-set). Prohibited supports stay out.
+     */
+    activeSupports?: readonly string[] | 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;
+    /** Catalogs referenced by this content (e.g. a test rubric block's catalogInfo). */
+    catalogs?: readonly CatalogView[] | undefined;
+    pnp?: PnpView | undefined;
+    activeSupports?: readonly string[] | undefined;
 }
 export interface QtiRuntime {
     ItemRenderer: ComponentType<ItemRendererProps>;
@@ -149,6 +235,13 @@ export interface QtiRuntime {
      */
     ContentRenderer: ComponentType<ContentRendererProps>;
     useAttempt: () => AttemptController;
+    /**
+     * The active supports resolved for a catalog idref — for skins whose own nodes
+     * carry data-catalog-idref (e.g. a choice label) and consumers building support
+     * UI (glossary panels, toggles). The core walk already decorates generic flow
+     * and block nodes; this is the same resolution by hand.
+     */
+    useCatalogSupports: (catalogIdref: string | undefined) => readonly ResolvedCatalogSupport[];
     /**
      * The Capability Report for an item against this runtime's injected descriptors,
      * skins, and content model. Consumers gate delivery on it (ADR-0003); the
@@ -161,4 +254,6 @@ export interface AttemptController extends AttemptSnapshot {
     submit: () => readonly ScoreResult[];
     reset: () => void;
 }
+/** The item-session states the renderer knows (ItemSessionControl review/solution). */
+export type ItemRenderMode = "interact" | "review" | "solution";
 export declare function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime;

package/dist/store.d.ts

@@ -11,6 +11,7 @@
  * support multiple attempts: outcomes carry over between RP runs and the item locks
  * only when `completionStatus` reaches "completed".
  */
+import type { InteractionConstraint, ResponseViolation } from "./response-validity";
 import type { CustomOperatorImplementation, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingView, TemplateDeclarationView, TemplateProcessingView } from "./rp";
 import type { ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
 export interface AttemptSnapshot {
@@ -24,6 +25,23 @@ export interface AttemptSnapshot {
     readonly templateValues: Readonly<Record<string, OutcomeValue>>;
     /** Completed attempts so far (only ever exceeds 1 for adaptive items). */
     readonly attemptCount: number;
+    /**
+     * Elapsed session seconds at the latest submit (the built-in `duration` response
+     * variable handed to RP); null before the first submit. Persist it alongside the
+     * responses for server-side replay parity (ADR-0004).
+     */
+    readonly durationSeconds: number | null;
+    /**
+     * Interaction constraints the current responses fail (see response-validity).
+     * Always visible so UIs can explain themselves; submission is blocked on them
+     * only under `validateResponses`.
+     */
+    readonly responseViolations: readonly ResponseViolation[];
+    /**
+     * This clone's resolved correct responses (template `setCorrectResponse` overrides
+     * applied), keyed by response identifier. The solution state renders these.
+     */
+    readonly correctResponses: Readonly<Record<string, ResponseValue>>;
 }
 /**
  * Consumer-supplied input. Optional members deliberately admit explicit
@@ -38,12 +56,32 @@ export interface AttemptStoreOptions {
     readonly normalization?: ResponseNormalization | undefined;
     readonly templateDeclarations?: readonly TemplateDeclarationView[] | undefined;
     readonly templateProcessing?: TemplateProcessingView | undefined;
+    /**
+     * Test-level `templateDefault` values (§5.152) overriding the template
+     * declarations' defaults for this clone; the test session store supplies them from
+     * the controller's recorded `templateDefaultValues`.
+     */
+    readonly templateDefaultValues?: Readonly<Record<string, OutcomeValue>> | 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;
+    /**
+     * Millisecond clock backing the built-in `duration` response variable (wall-clock
+     * from session start to submit). Injectable for deterministic tests and replays;
+     * defaults to Date.now.
+     */
+    readonly now?: (() => number) | undefined;
+    /** The item's interaction constraints (collectInteractionConstraints over the body). */
+    readonly constraints?: readonly InteractionConstraint[] | undefined;
+    /**
+     * ItemSessionControl validate-responses: "candidates are not allowed to submit the
+     * item until they have provided valid responses for all interactions". When set,
+     * submit() refuses while `responseViolations` is non-empty.
+     */
+    readonly validateResponses?: boolean | undefined;
 }
 export interface AttemptStore {
     readonly getSnapshot: () => AttemptSnapshot;
@@ -57,5 +95,14 @@ export interface AttemptStore {
     readonly registerResponseCollector: (responseIdentifier: string, collector: () => ResponseValue | undefined) => () => void;
     readonly submit: () => readonly ScoreResult[];
     readonly reset: () => void;
+    /**
+     * Stop the session clock: duration "records the accumulated time (in seconds) of
+     * all Candidate Sessions for all Attempts … minus any time the session was in the
+     * suspended state". Navigating away from an item suspends its session (spec);
+     * the test session store drives this. Idempotent.
+     */
+    readonly suspend: () => void;
+    /** Restart the session clock after `suspend()`. Idempotent. */
+    readonly resume: () => void;
 }
 export declare function createAttemptStore(declarations: readonly ResponseDeclarationView[], initialResponses: Readonly<Record<string, ResponseValue>>, options?: AttemptStoreOptions): AttemptStore;

package/dist/test/controller.d.ts

@@ -4,8 +4,30 @@
  * 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 PnpView } from "../pnp";
+import type { OutcomeDeclarationView } from "../rp/types";
 import type { AssessmentTestView, TestController } from "./types";
 export interface TestControllerOptions {
     readonly seed: number;
+    /**
+     * Each item's outcome declarations, keyed by item-ref identifier (shared by every
+     * selected instance of the ref). Feeds `outcomeMaximum`/`outcomeMinimum` with the declared
+     * `normal-maximum`/`normal-minimum`; items absent here degrade per spec — maximum
+     * → NULL (§2.11.2.7), minimum → ignored (§2.11.2.6) — never a refusal. Consumers
+     * can pass `assessmentItemViewFromNormalized(...).outcomeDeclarations` verbatim.
+     */
+    readonly itemOutcomeDeclarations?: Readonly<Record<string, readonly OutcomeDeclarationView[]>> | undefined;
+    /**
+     * Millisecond clock backing the built-in test/part/section `duration` variables and
+     * timeLimits enforcement. Injectable for deterministic tests and replays; defaults
+     * to Date.now.
+     */
+    readonly now?: (() => number) | undefined;
+    /**
+     * The candidate's AfA PNP. The controller consumes additional-testing-time:
+     * "the durations may be changed depending on the relevant accessibility values
+     * in the Personal Needs & Preferences settings for the learner" (§2.8.5).
+     */
+    readonly pnp?: PnpView | undefined;
 }
 export declare function createTestController(view: AssessmentTestView, options: TestControllerOptions): TestController;

package/dist/test/index.d.ts

@@ -1,3 +1,4 @@
 export { createTestController, type TestControllerOptions } from "./controller";
+export { assessmentResultFromNormalized, buildAssessmentResult, type AssessmentResultDocumentView, type AssessmentResultInput, type AssessmentResultItemDetails, type AssessmentResultView, type ItemResultView, type ResultContextView, type ResultOutcomeVariableView, type ResultResponseVariableView, type ResultSessionIdentifierView, type ResultSessionStatus, type ResultSupportView, type ResultValueView, type TestResultView, } from "./results";
 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";
+export type { AssessmentItemRefView, RecordedAttempt, AssessmentSectionView, AssessmentTestView, BranchRuleView, ItemSessionControlView, OutcomeConditionBranch, OutcomeRuleView, RejectedSubmission, TemplateDefaultView, TestController, TestFeedbackView, TestItemResult, TestPartView, TestPlan, TestPlanItem, TestPlanPart, TestPlanSection, TestSessionState, TestTimingState, TimeLimitsView, TimingScopeRef, } from "./types";