@conform-ed/qti-react 0.0.13 → 0.0.14

package/src/pci/mount.ts

@@ -8,7 +8,6 @@
 
 import type { BodyNode } from "../runtime";
 import type { ResponseDeclarationView, ResponseValue } from "../types";
-
 import { serializePciMarkup } from "./markup";
 import type { PciConfiguration, PciInstance, PciModule, PciModuleRegistry } from "./registry";
 import { pciResponseToValue, valueToPciResponse } from "./response";
@@ -110,7 +109,7 @@ export async function mountPci(options: PciMountOptions): Promise<PciMountHandle
       : {}),
     status: "interacting",
     onready: (instance) => resolveReady(instance),
-    ondone: (instance, response, state) => options.ondone?.(pciResponseToValue(response), state),
+    ondone: (_instance, response, state) => options.ondone?.(pciResponseToValue(response), state),
   };
 
   // The spec delivers the instance via onready; implementations commonly also return

package/src/pci/skin.ts

@@ -8,7 +8,6 @@
 import { createElement, useEffect, useRef, useState, type ReactNode } from "react";
 
 import type { InteractionRenderProps, InteractionSkin } from "../runtime";
-
 import { mountPci, type PciInteractionNode, type PciMountHandle } from "./mount";
 import type { PciModuleRegistry } from "./registry";
 

package/src/reference-skin/drawing.ts

@@ -5,10 +5,16 @@
  * Items using drawing are typically scored externally, not by client RP.
  */
 
-import { createElement, useEffect, useRef, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from "react";
 
 import type { BodyNode, InteractionRenderProps } from "../runtime";
-
 import type { ObjectView } from "./graphic-base";
 
 interface DrawingNodeView {
@@ -30,28 +36,32 @@ export function DrawingReferenceSkin(props: InteractionRenderProps): ReactNode {
   propsRef.current = props;
 
   // Paint the stage image as the drawing background (and again after a clear).
-  const paintBackground = (canvas: HTMLCanvasElement): void => {
-    const context = canvas.getContext("2d");
+  const stageData = node.object.data;
+  const paintBackground = useCallback(
+    (canvas: HTMLCanvasElement): void => {
+      const context = canvas.getContext("2d");
 
-    if (!context) {
-      return;
-    }
+      if (!context) {
+        return;
+      }
 
-    context.clearRect(0, 0, canvas.width, canvas.height);
+      context.clearRect(0, 0, canvas.width, canvas.height);
 
-    const image = new Image();
+      const image = new Image();
 
-    image.onload = () => {
-      context.drawImage(image, 0, 0, canvas.width, canvas.height);
-    };
-    image.src = propsRef.current.resolveAsset(node.object.data);
-  };
+      image.onload = () => {
+        context.drawImage(image, 0, 0, canvas.width, canvas.height);
+      };
+      image.src = propsRef.current.resolveAsset(stageData);
+    },
+    [stageData],
+  );
 
   useEffect(() => {
     if (canvasRef.current) {
       paintBackground(canvasRef.current);
     }
-  }, [node.object.data]);
+  }, [paintBackground]);
 
   const pointerPosition = (event: ReactPointerEvent<HTMLCanvasElement>): { x: number; y: number } => {
     const canvas = event.currentTarget;

package/src/reference-skin/index.ts

@@ -6,7 +6,6 @@
  */
 
 import type { SkinRegistry } from "../runtime";
-
 import { AssociateReferenceSkin } from "./associate";
 import { ChoiceReferenceSkin } from "./choice";
 import { DrawingReferenceSkin } from "./drawing";
@@ -17,13 +16,13 @@ import { GraphicAssociateReferenceSkin } from "./graphic-associate";
 import { GraphicGapMatchReferenceSkin } from "./graphic-gap-match";
 import { GraphicOrderReferenceSkin } from "./graphic-order";
 import { HotspotReferenceSkin } from "./hotspot";
-import { PositionObjectReferenceSkin } from "./position-object";
-import { SelectPointReferenceSkin } from "./select-point";
 import { HottextReferenceSkin } from "./hottext";
 import { InlineChoiceReferenceSkin } from "./inline-choice";
 import { MatchReferenceSkin } from "./match";
 import { MediaReferenceSkin } from "./media";
 import { OrderReferenceSkin } from "./order";
+import { PositionObjectReferenceSkin } from "./position-object";
+import { SelectPointReferenceSkin } from "./select-point";
 import { SliderReferenceSkin } from "./slider";
 import { TextEntryReferenceSkin } from "./text-entry";
 import { UploadReferenceSkin } from "./upload";

package/src/rp/evaluate.ts

@@ -9,12 +9,12 @@
 import { parseCoords, parsePoint, pointInShape } from "../graphic";
 import { mapResponse, mapResponsePoint } from "../response-processing";
 import type { ResponseDeclarationView, ResponseValue } from "../types";
-
 import type { CustomOperatorImplementation, ResponseNormalization, RpExpressionView } from "./types";
 import {
   booleanValue,
   coerceScalar,
   floatValue,
+  rpValue,
   scalarsEqual,
   singleBoolean,
   singleNumber,
@@ -27,19 +27,19 @@ export interface EvalEnv {
   readonly lookupVariable: (identifier: string) => MaybeRpValue;
   readonly responseDeclaration: (identifier: string) => ResponseDeclarationView | undefined;
   readonly responseValue: (identifier: string) => ResponseValue;
-  readonly normalization?: ResponseNormalization;
+  readonly normalization?: ResponseNormalization | undefined;
   /** Seeded PRNG in [0, 1); present only in template processing. */
-  readonly random?: () => number;
+  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>>;
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }
 
 /** Expression kinds legal everywhere (deterministic). */
-export const deterministicExpressionKinds = new Set([
+export const deterministicExpressionKinds: ReadonlySet<string> = new Set([
   "and",
   "baseValue",
   "correct",
@@ -86,11 +86,14 @@ export const deterministicExpressionKinds = new Set([
 ]);
 
 /** Expression kinds requiring the seeded PRNG (template processing only). */
-export const randomExpressionKinds = new Set(["random", "randomFloat", "randomInteger"]);
+export const randomExpressionKinds: ReadonlySet<string> = new Set(["random", "randomFloat", "randomInteger"]);
 
 export class RpUnsupportedError extends Error {
-  constructor(readonly kindName: string) {
+  readonly kindName: string;
+
+  constructor(kindName: string) {
     super(`Unsupported response-processing construct: ${kindName}`);
+    this.kindName = kindName;
   }
 }
 
@@ -190,7 +193,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
       const baseType = expression.baseType;
       const value = expression.value;
 
-      return value === undefined ? null : { cardinality: "single", baseType, values: [coerceScalar(value, baseType)] };
+      return value === undefined ? null : rpValue("single", [coerceScalar(value, baseType)], baseType);
     }
 
     case "variable":
@@ -203,11 +206,11 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return null;
       }
 
-      return {
-        cardinality: declaration.cardinality,
-        baseType: declaration.baseType,
-        values: declaration.correctResponse.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
-      };
+      return rpValue(
+        declaration.cardinality,
+        declaration.correctResponse.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+        declaration.baseType,
+      );
     }
 
     case "mapResponse": {
@@ -260,9 +263,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
       const value = operand === undefined ? null : evaluate(operand);
       const field = value?.fields?.find((entry) => entry.name === expression.fieldIdentifier);
 
-      return field === undefined
-        ? null
-        : { cardinality: "single", ...(field.baseType ? { baseType: field.baseType } : {}), values: [field.value] };
+      return field === undefined ? null : rpValue("single", [field.value], field.baseType);
     }
 
     case "and":
@@ -392,7 +393,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return null; // out of range is null, per spec
       }
 
-      return { cardinality: "single", baseType: container.baseType, values: [member] };
+      return rpValue("single", [member], container.baseType);
     }
 
     case "mathConstant": {
@@ -603,9 +604,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
       const remaining = container.values.filter((member) => !scalarsEqual(member, scalar, baseType, env.normalization));
 
       // An empty container is NULL, per the QTI value model.
-      return remaining.length === 0
-        ? null
-        : { cardinality: container.cardinality, baseType: container.baseType, values: remaining };
+      return remaining.length === 0 ? null : rpValue(container.cardinality, remaining, container.baseType);
     }
 
     case "repeat": {
@@ -633,7 +632,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         }
       }
 
-      return members.length === 0 ? null : { cardinality: "ordered", baseType, values: members };
+      return members.length === 0 ? null : rpValue("ordered", members, baseType);
     }
 
     case "stringMatch":
@@ -728,7 +727,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return null;
       }
 
-      return { cardinality: expression.kind, baseType, values: members };
+      return rpValue(expression.kind, members, baseType);
     }
 
     case "randomInteger": {
@@ -798,7 +797,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
 
       const pick = container.values[Math.floor(env.random() * container.values.length)]!;
 
-      return { cardinality: "single", baseType: container.baseType, values: [pick] };
+      return rpValue("single", [pick], container.baseType);
     }
 
     default:

package/src/rp/interpreter.ts

@@ -7,7 +7,6 @@
 
 import type { CapabilityIssue } from "../capability";
 import type { ResponseDeclarationView } from "../types";
-
 import {
   RpUnsupportedError,
   collectExpressionIssues,
@@ -30,6 +29,7 @@ import {
   fromFlatValue,
   fromResponse,
   isNumericBaseType,
+  rpValue,
   singleBoolean,
   toOutcomeValue,
   type MaybeRpValue,
@@ -50,11 +50,14 @@ function defaultOutcomes(declarations: readonly OutcomeDeclarationView[]): Map<s
 
   for (const declaration of declarations) {
     if (declaration.defaultValue) {
-      outcomes.set(declaration.identifier, {
-        cardinality: declaration.cardinality,
-        baseType: declaration.baseType,
-        values: declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
-      });
+      outcomes.set(
+        declaration.identifier,
+        rpValue(
+          declaration.cardinality,
+          declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+          declaration.baseType,
+        ),
+      );
       continue;
     }
 

package/src/rp/template-processing.ts

@@ -8,7 +8,6 @@
 
 import type { CapabilityIssue } from "../capability";
 import type { CorrectResponseView, ResponseDeclarationView } from "../types";
-
 import {
   RpUnsupportedError,
   collectExpressionIssues,
@@ -18,7 +17,7 @@ import {
   type EvalEnv,
 } from "./evaluate";
 import type { CustomOperatorImplementation, OutcomeValue, RpExpressionView, TemplateDeclarationView } from "./types";
-import { coerceScalar, singleBoolean, toOutcomeValue, type MaybeRpValue } from "./values";
+import { coerceScalar, rpValue, singleBoolean, toOutcomeValue, type MaybeRpValue } from "./values";
 
 export interface TemplateConditionBranch {
   readonly expression: RpExpressionView;
@@ -43,7 +42,7 @@ export interface TemplateProcessingContext {
   readonly responseDeclarations: readonly ResponseDeclarationView[];
   readonly seed: number;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
-  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }
 
 export interface TemplateProcessingResult {
@@ -101,11 +100,11 @@ export function executeTemplateProcessing(
       values.set(
         declaration.identifier,
         declaration.defaultValue
-          ? {
-              cardinality: declaration.cardinality,
-              baseType: declaration.baseType,
-              values: declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
-            }
+          ? rpValue(
+              declaration.cardinality,
+              declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+              declaration.baseType,
+            )
           : null,
       );
     }
@@ -153,11 +152,7 @@ export function executeTemplateProcessing(
             rule.identifier,
             value === null || !declaration
               ? value
-              : {
-                  cardinality: declaration.cardinality,
-                  baseType: declaration.baseType ?? value.baseType,
-                  values: value.values,
-                },
+              : rpValue(declaration.cardinality, value.values, declaration.baseType ?? value.baseType),
           );
         }
         continue;

package/src/rp/types.ts

@@ -134,24 +134,30 @@ export interface TemplateDeclarationView {
   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;
+  readonly normalization?: ResponseNormalization | undefined;
   /** Template variables for this clone (read by `variable` lookups). */
-  readonly templateDeclarations?: readonly TemplateDeclarationView[];
-  readonly templateValues?: Readonly<Record<string, OutcomeValue>>;
+  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>>;
+  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;
+  readonly random?: (() => number) | undefined;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
-  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }
 
 export interface ResponseProcessingResult {

package/src/rp/values.ts

@@ -61,11 +61,11 @@ export function fromResponse(declaration: ResponseDeclarationView, response: Res
     return null;
   }
 
-  return {
-    cardinality: declaration.cardinality,
-    baseType: declaration.baseType,
-    values: raw.map((value) => coerceScalar(value, declaration.baseType)),
-  };
+  return rpValue(
+    declaration.cardinality,
+    raw.map((value) => coerceScalar(value, declaration.baseType)),
+    declaration.baseType,
+  );
 }
 
 export function singleNumber(value: MaybeRpValue): number | null {
@@ -88,6 +88,15 @@ export function singleBoolean(value: MaybeRpValue): boolean | null {
   return typeof member === "boolean" ? member : null;
 }
 
+/** Construct a typed value; an unknown baseType is omitted, never stored as undefined. */
+export function rpValue(cardinality: Cardinality, values: readonly RpScalar[], baseType?: string): RpValue {
+  return {
+    cardinality,
+    values,
+    ...(baseType !== undefined ? { baseType } : {}),
+  };
+}
+
 export function booleanValue(value: boolean): RpValue {
   return { cardinality: "single", baseType: "boolean", values: [value] };
 }
@@ -182,7 +191,11 @@ export function fromFlatValue(value: OutcomeValue, cardinality: Cardinality, bas
     return null;
   }
 
-  return { cardinality, baseType, values: values.map((member) => coerceScalar(member, baseType)) };
+  return rpValue(
+    cardinality,
+    values.map((member) => coerceScalar(member, baseType)),
+    baseType,
+  );
 }
 
 export function toOutcomeValue(value: MaybeRpValue): OutcomeValue {

package/src/runtime.ts

@@ -175,9 +175,9 @@ export interface ItemRendererProps {
    * per-mount store; passing one enables review/replay modes (rehydrate a stored,
    * already-submitted attempt) and server-side rendering of submitted states.
    */
-  store?: AttemptStore;
+  store?: AttemptStore | undefined;
   /** Clone seed for template processing; store it to replay the same clone. */
-  seed?: number;
+  seed?: number | undefined;
   // Rendered inside the same runtime context as the item body, after it. Lets a consumer
   // drop controls (a Submit bar, a score panel) that call `useAttempt()` for this item —
   // the attempt store is per-item and scoped to this subtree.
@@ -185,9 +185,9 @@ export interface ItemRendererProps {
 }
 
 export interface ContentRendererProps {
-  nodes?: readonly BodyNode[];
+  nodes?: readonly BodyNode[] | undefined;
   /** Values for printedVariable (and showHide-gated feedback) inside the content. */
-  outcomes?: Readonly<Record<string, OutcomeValue>>;
+  outcomes?: Readonly<Record<string, OutcomeValue>> | undefined;
 }
 
 export interface QtiRuntime {
@@ -437,7 +437,7 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   }: {
     feedback: FeedbackView;
     element: "span" | "div";
-    overrides?: NodeOverrides;
+    overrides?: NodeOverrides | undefined;
   }): ReactNode {
     const { store } = useRuntimeContext();
     const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
@@ -461,7 +461,7 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   }: {
     view: TemplateContentView;
     element: "span" | "div";
-    overrides?: NodeOverrides;
+    overrides?: NodeOverrides | undefined;
   }): ReactNode {
     const { store } = useRuntimeContext();
     const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
@@ -693,11 +693,13 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
         const parsed = descriptor.schema.safeParse(node);
 
         if (!parsed.success) {
+          const detail = parsed.error.issues[0]?.message;
+
           report({
             type: "invalid-interaction",
             name: node.kind,
             responseIdentifier: node.responseIdentifier,
-            detail: parsed.error.issues[0]?.message,
+            ...(detail !== undefined ? { detail } : {}),
           });
         }
 

package/src/store.ts

@@ -38,19 +38,25 @@ export interface AttemptSnapshot {
   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[];
-  readonly responseProcessing?: ResponseProcessingView;
+  readonly outcomeDeclarations?: readonly OutcomeDeclarationView[] | undefined;
+  readonly responseProcessing?: ResponseProcessingView | undefined;
   /** The Response Normalization hook (ADR-0004); applies to scores and outcomes alike. */
-  readonly normalization?: ResponseNormalization;
-  readonly templateDeclarations?: readonly TemplateDeclarationView[];
-  readonly templateProcessing?: TemplateProcessingView;
+  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;
+  readonly seed?: number | undefined;
   /** QTI adaptive item: multiple attempts, outcome carry-over, completionStatus lock. */
-  readonly adaptive?: boolean;
+  readonly adaptive?: boolean | undefined;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
-  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }
 
 export interface AttemptStore {

package/src/test/controller.ts

@@ -20,12 +20,12 @@ import {
   floatValue,
   fromFlatValue,
   isNumericBaseType,
+  rpValue,
   singleBoolean,
   toOutcomeValue,
   type MaybeRpValue,
   type RpValue,
 } from "../rp/values";
-
 import type {
   AssessmentItemRefView,
   AssessmentSectionView,
@@ -262,11 +262,14 @@ export function createTestController(view: AssessmentTestView, options: TestCont
 
     for (const declaration of view.outcomeDeclarations ?? []) {
       if (declaration.defaultValue) {
-        outcomes.set(declaration.identifier, {
-          cardinality: declaration.cardinality,
-          baseType: declaration.baseType,
-          values: declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
-        });
+        outcomes.set(
+          declaration.identifier,
+          rpValue(
+            declaration.cardinality,
+            declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+            declaration.baseType,
+          ),
+        );
         continue;
       }
 
@@ -331,7 +334,7 @@ export function createTestController(view: AssessmentTestView, options: TestCont
           members.push(...lifted.values);
         }
 
-        return members.length === 0 ? null : { cardinality: "multiple", baseType, values: members };
+        return members.length === 0 ? null : rpValue("multiple", members, baseType);
       },
       testAggregate: (expression) => {
         const subset = subsetItems(expression);

package/src/test/session-store.ts

@@ -12,7 +12,6 @@ import type { AssessmentItemView } from "../runtime";
 import { createAttemptStore, type AttemptSnapshot, type AttemptStore } from "../store";
 import { isResponseRecord } from "../types";
 import type { ResponseValue } from "../types";
-
 import type { AssessmentItemRefView, TestController, TestFeedbackView, TestPlanItem, TestSessionState } from "./types";
 
 export interface TestSessionStoreOptions {