@conform-ed/qti-react 0.0.18 → 0.0.19

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export declare const qtiReactPackageName = "@conform-ed/qti-react";
 export { v0ContentModel, v0InteractionKinds, isAllowedFlowElement, isInteractionKind, sanitizeAttributes, type ContentModel, type V0InteractionKind, } from "./content-model";
 export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
+export { effectiveItemScore, type EffectiveItemScore } from "./item-score";
 export { assessmentItemViewFromNormalized, assessmentTestViewFromNormalized, stimulusContentFromNormalized, } from "./normalized-item";
 export { referenceInteractionKinds, reportItemCapability, type ItemCapabilityOptions } from "./item-capability";
 export { formatPoint, parseCoords, parsePoint, pointInShape, type Point, type QtiShape } from "./graphic";

package/dist/index.js

@@ -387,6 +387,23 @@ function scoreResponse(declaration, response, normalize) {
     correct
   };
 }
+// src/item-score.ts
+function numericOutcome(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function effectiveItemScore(scores, outcomes) {
+  const scoreOutcome = numericOutcome(outcomes["SCORE"]);
+  const maxOutcome = numericOutcome(outcomes["MAXSCORE"]);
+  const summedMax = scores.reduce((total, score) => total + score.maxScore, 0);
+  if (scoreOutcome !== null) {
+    return { raw: scoreOutcome, max: maxOutcome ?? summedMax, fromOutcomes: true };
+  }
+  return {
+    raw: scores.reduce((total, score) => total + score.score, 0),
+    max: maxOutcome ?? summedMax,
+    fromOutcomes: false
+  };
+}
 // src/normalized-item.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -6836,6 +6853,7 @@ export {
   executeTemplateProcessing,
   executeResponseProcessing,
   endAttemptInteraction,
+  effectiveItemScore,
   drawingInteraction,
   defineInteraction,
   createTestSessionStore,

package/dist/item-score.d.ts

@@ -0,0 +1,17 @@
+import type { ScoreResult } from "./types";
+export interface EffectiveItemScore {
+    readonly raw: number;
+    readonly max: number;
+    /** True when SCORE came from the RP outcomes of record rather than per-variable scoring. */
+    readonly fromOutcomes: boolean;
+}
+/**
+ * The item score of record (QTI): a numeric SCORE outcome from response processing is
+ * authoritative — PCI/RP-scored items (e.g. math-entry) have no per-variable
+ * correctResponse basis, so their standard scores read 0. Summed per-variable standard
+ * scoring is the fallback for items without RP. MAXSCORE follows the same precedence.
+ *
+ * Pure and framework-light: client and server (authoritative finalize) share it so the
+ * grade of record is derived identically on both sides.
+ */
+export declare function effectiveItemScore(scores: readonly ScoreResult[], outcomes: Readonly<Record<string, unknown>>): EffectiveItemScore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conform-ed/qti-react",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "files": [
     "src",
     "dist"
@@ -30,11 +30,11 @@
     "xspattern": "^3.1.0"
   },
   "devDependencies": {
-    "@conform-ed/contracts": "0.0.18",
-    "@conform-ed/qti-xml": "0.0.18",
+    "@conform-ed/contracts": "0.0.19",
+    "@conform-ed/qti-xml": "0.0.19",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19",
-    "happy-dom": "^20.10.2",
+    "happy-dom": "^20.10.3",
     "react": "^19.2.7",
     "react-dom": "^19"
   },

package/src/headless.ts

@@ -1,11 +1,15 @@
 /**
- * Headless (React-free) surface of @conform-ed/qti-react: the normalize → view adapters
- * and the capability gate, importable on a server (e.g. a QTI ingest pipeline) without
- * pulling React. Exposed at `@conform-ed/qti-react/headless`; everything here is also
- * re-exported from the package root for React consumers.
+ * Headless (React-free) surface of @conform-ed/qti-react: the normalize → view adapters,
+ * the capability gate, and the **scoring engine** (Response Processing interpreter, the
+ * standard per-response scoring templates, the item-score aggregator, and the test-level
+ * outcome-processing controller). Importable on a server (e.g. a QTI ingest pipeline or an
+ * authoritative grade finalize) without pulling React. Exposed at
+ * `@conform-ed/qti-react/headless`; everything here is also re-exported from the package
+ * root for React consumers.
  *
- * Keep this entry free of React-coupled imports — only ./normalized-item and
- * ./item-capability (value) plus type-only re-exports.
+ * Keep this entry free of React-coupled imports — every module re-exported here
+ * (./normalized-item, ./item-capability, ./response-processing, ./rp, ./item-score,
+ * ./store, ./test, ./response-validity) is verified framework-light.
  */
 
 export {
@@ -14,6 +18,33 @@ export {
   stimulusContentFromNormalized,
 } from "./normalized-item";
 export { referenceInteractionKinds, reportItemCapability, type ItemCapabilityOptions } from "./item-capability";
+
+// The scoring engine, headless. Running these server-side re-derives the grade of record
+// from the learner's raw responses + the (server-held) answer keys — see emergent ADR-0019.
+export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
+export { effectiveItemScore, type EffectiveItemScore } from "./item-score";
+export {
+  applyCorrectResponseOverrides,
+  collectRpIssues,
+  collectTemplateIssues,
+  executeResponseProcessing,
+  executeTemplateProcessing,
+  mulberry32,
+  resolveTemplate,
+} from "./rp";
+export type {
+  CustomOperatorImplementation,
+  OutcomeDeclarationView,
+  OutcomeValue,
+  ResponseNormalization,
+  ResponseProcessingContext,
+  ResponseProcessingResult,
+  ResponseProcessingView,
+  TemplateDeclarationView,
+} from "./rp";
+export { createAttemptStore, type AttemptSnapshot, type AttemptStore, type AttemptStoreOptions } from "./store";
+export { createTestController, type TestController, type TestSessionState } from "./test";
+
 export type { CapabilityIssue, CapabilityIssueType, CapabilityReport } from "./capability";
 export type {
   AssessmentItemView,
@@ -24,3 +55,4 @@ export type {
   XmlContentNode,
 } from "./runtime";
 export type { AssessmentTestView } from "./test";
+export type { Cardinality, ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";

package/src/index.ts

@@ -14,6 +14,8 @@ export {
 
 export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
 
+export { effectiveItemScore, type EffectiveItemScore } from "./item-score";
+
 export {
   assessmentItemViewFromNormalized,
   assessmentTestViewFromNormalized,

package/src/item-score.ts

@@ -0,0 +1,40 @@
+import type { ScoreResult } from "./types";
+
+export interface EffectiveItemScore {
+  readonly raw: number;
+  readonly max: number;
+  /** True when SCORE came from the RP outcomes of record rather than per-variable scoring. */
+  readonly fromOutcomes: boolean;
+}
+
+function numericOutcome(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * The item score of record (QTI): a numeric SCORE outcome from response processing is
+ * authoritative — PCI/RP-scored items (e.g. math-entry) have no per-variable
+ * correctResponse basis, so their standard scores read 0. Summed per-variable standard
+ * scoring is the fallback for items without RP. MAXSCORE follows the same precedence.
+ *
+ * Pure and framework-light: client and server (authoritative finalize) share it so the
+ * grade of record is derived identically on both sides.
+ */
+export function effectiveItemScore(
+  scores: readonly ScoreResult[],
+  outcomes: Readonly<Record<string, unknown>>,
+): EffectiveItemScore {
+  const scoreOutcome = numericOutcome(outcomes["SCORE"]);
+  const maxOutcome = numericOutcome(outcomes["MAXSCORE"]);
+  const summedMax = scores.reduce((total, score) => total + score.maxScore, 0);
+
+  if (scoreOutcome !== null) {
+    return { raw: scoreOutcome, max: maxOutcome ?? summedMax, fromOutcomes: true };
+  }
+
+  return {
+    raw: scores.reduce((total, score) => total + score.score, 0),
+    max: maxOutcome ?? summedMax,
+    fromOutcomes: false,
+  };
+}