@conform-ed/qti-react 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 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";
 export { applyCorrectResponseOverrides, collectRpIssues, collectTemplateIssues, executeResponseProcessing, executeTemplateProcessing, mulberry32, resolveTemplate, } from "./rp";
 export type { CustomOperatorImplementation, InterpolationTableEntryView, InterpolationTableView, MatchTableEntryView, MatchTableView, MaybeRpValue, OutcomeDeclarationView, OutcomeValue, ResponseNormalization, ResponseProcessingContext, ResponseProcessingResult, ResponseProcessingView, RpConditionBranch, RpExpressionView, RpRecordField, RpRuleView, RpScalar, RpValue, TemplateConditionBranch, TemplateDeclarationView, TemplateProcessingContext, TemplateProcessingResult, TemplateProcessingView, TemplateRuleView, } from "./rp";

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);
@@ -2930,6 +2947,127 @@ function collectTemplateIssues(view, options) {
   walkRules(view.rules);
   return issues;
 }
+// src/item-capability.ts
+var feedbackKinds = new Set(["feedbackInline", "feedbackBlock"]);
+var templateContentKinds = new Set(["templateInline", "templateBlock"]);
+var intrinsicLeafKinds = new Set(["text", "printedVariable"]);
+function isFeedbackNode(node) {
+  return feedbackKinds.has(node.kind);
+}
+function isTemplateContentNode(node) {
+  return templateContentKinds.has(node.kind);
+}
+function isInteractionNode(node) {
+  return node.kind !== "xml" && typeof node.responseIdentifier === "string";
+}
+function reportItemCapability(item, options) {
+  const model = options.model ?? v0ContentModel;
+  const customOperatorClasses = options.customOperatorClasses ?? new Set;
+  const issues = [];
+  const seen = new Set;
+  function report(issue) {
+    const dedupeKey = `${issue.type}:${issue.name}:${issue.responseIdentifier ?? ""}`;
+    if (!seen.has(dedupeKey)) {
+      seen.add(dedupeKey);
+      issues.push(issue);
+    }
+  }
+  function walk(node) {
+    if (isFeedbackNode(node) || isTemplateContentNode(node) || node.kind === "rubricBlock") {
+      for (const child of node.content ?? []) {
+        walk(child);
+      }
+      return;
+    }
+    if (isInteractionNode(node)) {
+      if (!options.supportedInteractions.has(node.kind)) {
+        report({ type: "unsupported-interaction", name: node.kind, responseIdentifier: node.responseIdentifier });
+        return;
+      }
+      const schema = options.interactionSchemas?.get(node.kind);
+      if (schema) {
+        const parsed = schema.safeParse(node);
+        if (!parsed.success) {
+          const detail = parsed.error.issues[0]?.message;
+          report({
+            type: "invalid-interaction",
+            name: node.kind,
+            responseIdentifier: node.responseIdentifier,
+            ...detail !== undefined ? { detail } : {}
+          });
+        }
+      }
+      return;
+    }
+    if (node.kind === "xml") {
+      const xmlNode = node;
+      if (xmlNode.name === model.mathRoot) {
+        return;
+      }
+      if (!isAllowedFlowElement(model, xmlNode.name)) {
+        report({ type: "unsupported-element", name: xmlNode.name });
+      }
+      for (const child of xmlNode.children ?? []) {
+        walk(child);
+      }
+      return;
+    }
+    if (intrinsicLeafKinds.has(node.kind)) {
+      return;
+    }
+    report({ type: "unsupported-element", name: node.kind });
+  }
+  for (const node of item.itemBody.content ?? []) {
+    walk(node);
+  }
+  for (const ref of item.assessmentStimulusRefs ?? []) {
+    const stimulus = options.resolveStimulus?.(ref) ?? null;
+    if (stimulus === null) {
+      report({ type: "unsupported-element", name: "assessmentStimulusRef", detail: ref.href });
+      continue;
+    }
+    for (const node of stimulus.content) {
+      walk(node);
+    }
+  }
+  for (const feedback of item.modalFeedbacks ?? []) {
+    for (const child of feedback.content ?? []) {
+      walk(child);
+    }
+  }
+  for (const issue of collectRpIssues(item.responseProcessing, {
+    customOperatorClasses,
+    outcomeDeclarations: item.outcomeDeclarations ?? []
+  })) {
+    report(issue);
+  }
+  for (const issue of collectTemplateIssues(item.templateProcessing, { customOperatorClasses })) {
+    report(issue);
+  }
+  return { deliverable: issues.length === 0, issues };
+}
+var referenceInteractionKinds = [
+  "associateInteraction",
+  "choiceInteraction",
+  "drawingInteraction",
+  "endAttemptInteraction",
+  "extendedTextInteraction",
+  "gapMatchInteraction",
+  "graphicAssociateInteraction",
+  "graphicGapMatchInteraction",
+  "graphicOrderInteraction",
+  "hotspotInteraction",
+  "hottextInteraction",
+  "inlineChoiceInteraction",
+  "matchInteraction",
+  "mediaInteraction",
+  "orderInteraction",
+  "positionObjectStage",
+  "selectPointInteraction",
+  "sliderInteraction",
+  "textEntryInteraction",
+  "uploadInteraction"
+];
 // src/response-validity.ts
 var countConstraintKinds = ["minChoices", "maxChoices", "minAssociations", "maxAssociations", "minStrings"];
 function collectInteractionConstraints(content) {
@@ -4669,22 +4807,21 @@ function responseIncludes(value, optionIdentifier) {
 function isCorrectOption(declaration, optionIdentifier) {
   return Boolean(declaration?.correctResponse?.values.some((entry) => entry.value === optionIdentifier));
 }
-function isInteractionNode(node) {
+function isInteractionNode2(node) {
   return node.kind !== "xml" && typeof node.responseIdentifier === "string";
 }
-var feedbackKinds = new Set(["feedbackInline", "feedbackBlock"]);
-function isFeedbackNode(node) {
-  return feedbackKinds.has(node.kind);
+var feedbackKinds2 = new Set(["feedbackInline", "feedbackBlock"]);
+function isFeedbackNode2(node) {
+  return feedbackKinds2.has(node.kind);
 }
-var templateContentKinds = new Set(["templateInline", "templateBlock"]);
-function isTemplateContentNode(node) {
-  return templateContentKinds.has(node.kind);
+var templateContentKinds2 = new Set(["templateInline", "templateBlock"]);
+function isTemplateContentNode2(node) {
+  return templateContentKinds2.has(node.kind);
 }
 function templateVisible(value, view) {
   const matched = Array.isArray(value) ? value.includes(view.identifier) : value === view.identifier;
   return matched !== (view.showHide === "hide");
 }
-var intrinsicLeafKinds = new Set(["text", "printedVariable"]);
 function createStaticStore(outcomes) {
   const snapshot = {
     responses: {},
@@ -4782,13 +4919,13 @@ function createQtiRuntime(config) {
     if (override) {
       return createElement(Fragment, { key }, override(node, key));
     }
-    if (isInteractionNode(node)) {
+    if (isInteractionNode2(node)) {
       if (descriptorsByKind.has(node.kind) && config.skin[node.kind]) {
         return createElement(InteractionHost, { key, node });
       }
       return renderUnsupported(node, key);
     }
-    if (isFeedbackNode(node)) {
+    if (isFeedbackNode2(node)) {
       return createElement(FeedbackHost, {
         key,
         feedback: node,
@@ -4796,7 +4933,7 @@ function createQtiRuntime(config) {
         overrides
       });
     }
-    if (isTemplateContentNode(node)) {
+    if (isTemplateContentNode2(node)) {
       return createElement(TemplateContentHost, {
         key,
         view: node,
@@ -5039,91 +5176,15 @@ function createQtiRuntime(config) {
     return catalogIdref !== undefined ? catalogSupports.get(catalogIdref) ?? noSupports : noSupports;
   }
   function canDeliver(item) {
-    const issues = [];
-    const seen = new Set;
-    function report(issue) {
-      const dedupeKey = `${issue.type}:${issue.name}:${issue.responseIdentifier ?? ""}`;
-      if (!seen.has(dedupeKey)) {
-        seen.add(dedupeKey);
-        issues.push(issue);
-      }
-    }
-    function walk(node) {
-      if (isFeedbackNode(node) || isTemplateContentNode(node) || node.kind === "rubricBlock") {
-        for (const child of node.content ?? []) {
-          walk(child);
-        }
-        return;
-      }
-      if (isInteractionNode(node)) {
-        const descriptor = descriptorsByKind.get(node.kind);
-        if (!descriptor || !config.skin[node.kind]) {
-          report({
-            type: "unsupported-interaction",
-            name: node.kind,
-            responseIdentifier: node.responseIdentifier
-          });
-          return;
-        }
-        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 !== undefined ? { detail } : {}
-          });
-        }
-        return;
-      }
-      if (node.kind === "xml") {
-        const xmlNode = node;
-        if (xmlNode.name === model.mathRoot) {
-          return;
-        }
-        if (!isAllowedFlowElement(model, xmlNode.name)) {
-          report({ type: "unsupported-element", name: xmlNode.name });
-        }
-        for (const child of xmlNode.children ?? []) {
-          walk(child);
-        }
-        return;
-      }
-      if (intrinsicLeafKinds.has(node.kind)) {
-        return;
-      }
-      report({ type: "unsupported-element", name: node.kind });
-    }
-    for (const node of item.itemBody.content ?? []) {
-      walk(node);
-    }
-    for (const ref of item.assessmentStimulusRefs ?? []) {
-      const stimulus = config.resolveStimulus?.(ref) ?? null;
-      if (stimulus === null) {
-        report({ type: "unsupported-element", name: "assessmentStimulusRef", detail: ref.href });
-        continue;
-      }
-      for (const node of stimulus.content) {
-        walk(node);
-      }
-    }
-    for (const feedback of item.modalFeedbacks ?? []) {
-      for (const child of feedback.content ?? []) {
-        walk(child);
-      }
-    }
-    const customOperatorClasses = new Set(Object.keys(config.customOperators ?? {}));
-    for (const issue of collectRpIssues(item.responseProcessing, {
-      customOperatorClasses,
-      outcomeDeclarations: item.outcomeDeclarations ?? []
-    })) {
-      report(issue);
-    }
-    for (const issue of collectTemplateIssues(item.templateProcessing, { customOperatorClasses })) {
-      report(issue);
-    }
-    return { deliverable: issues.length === 0, issues };
+    const supportedInteractions = new Set([...descriptorsByKind.keys()].filter((kind) => Boolean(config.skin[kind])));
+    const interactionSchemas = new Map([...descriptorsByKind].map(([kind, descriptor]) => [kind, descriptor.schema]));
+    return reportItemCapability(item, {
+      supportedInteractions,
+      interactionSchemas,
+      model,
+      customOperatorClasses: new Set(Object.keys(config.customOperators ?? {})),
+      ...config.resolveStimulus !== undefined ? { resolveStimulus: config.resolveStimulus } : {}
+    });
   }
   return { ItemRenderer, ContentRenderer, useAttempt, useCatalogSupports, canDeliver };
 }
@@ -6758,7 +6819,9 @@ export {
   resolveTemplate,
   resolvePnpActivation,
   resolveCatalogSupports,
+  reportItemCapability,
   referenceSkin,
+  referenceInteractionKinds,
   qtiReactPackageName,
   qtiCoreInteractions,
   positionObjectStage,
@@ -6790,6 +6853,7 @@ export {
   executeTemplateProcessing,
   executeResponseProcessing,
   endAttemptInteraction,
+  effectiveItemScore,
   drawingInteraction,
   defineInteraction,
   createTestSessionStore,

package/dist/item-capability.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Headless capability gate (ADR-0003): "can a runtime that supports `supportedInteractions`
+ * deliver this item, and if not, why" — extracted from the React runtime's `canDeliver`
+ * so server-side callers (e.g. an ingest pipeline) can reach the *same* decision without
+ * importing React. The React runtime delegates to this, passing the interaction set its
+ * descriptors + skins cover; a headless caller passes the set its delivery supports.
+ *
+ * This module is React-free by construction (content-model + RP collectors only; the view
+ * shapes are type-only imports), so it ships through the `@conform-ed/qti-react/headless`
+ * entry alongside the normalize → view adapters.
+ */
+import type { ZodType } from "zod";
+import type { CapabilityReport } from "./capability";
+import { type ContentModel } from "./content-model";
+import type { AssessmentItemView, AssessmentStimulusRefView, StimulusContentView } from "./runtime";
+export interface ItemCapabilityOptions {
+    /** Interaction kinds the target runtime can render (descriptor + skin both present). */
+    readonly supportedInteractions: ReadonlySet<string>;
+    /** Content model deciding the flow-element allowlist + math root; defaults to v0. */
+    readonly model?: ContentModel;
+    /** Custom-operator classes the target runtime registers (for RP capability). */
+    readonly customOperatorClasses?: ReadonlySet<string>;
+    /** Resolver for shared-stimulus refs; unresolved refs are not deliverable. */
+    readonly resolveStimulus?: (ref: AssessmentStimulusRefView) => StimulusContentView | null;
+    /**
+     * Optional per-kind schemas for the stricter `invalid-interaction` check. The React
+     * runtime supplies its descriptor schemas; a headless caller that has already validated
+     * structure (e.g. against the qti-xml contracts schema) can omit them.
+     */
+    readonly interactionSchemas?: ReadonlyMap<string, ZodType>;
+}
+/**
+ * Report whether `item` can be delivered by a runtime with the given capabilities, and
+ * every reason it cannot. Pure and React-free; the React runtime's `canDeliver` is a thin
+ * wrapper over this.
+ */
+export declare function reportItemCapability(item: AssessmentItemView, options: ItemCapabilityOptions): CapabilityReport;
+/**
+ * Interaction kinds the bundled reference skin renders — the default "supported set" for
+ * callers that deliver with the reference skin. Kept in parity with the reference skin by
+ * a test; pass an explicit set to `reportItemCapability` for a custom delivery surface.
+ */
+export declare const referenceInteractionKinds: readonly string[];

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.17",
+  "version": "0.0.19",
   "files": [
     "src",
     "dist"
@@ -12,10 +12,15 @@
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./headless": {
+      "development": "./src/headless.ts",
+      "types": "./dist/headless.d.ts",
+      "import": "./dist/headless.js"
     }
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --external react --external react-dom --external zod && tsgo -p tsconfig.build.json",
+    "build": "bun build ./src/index.ts ./src/headless.ts --outdir dist --format esm --target browser --external react --external react-dom --external zod && tsgo -p tsconfig.build.json",
     "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
     "lint": "oxlint --config ../../.oxlintrc.jsonc .",
     "test": "bun test",
@@ -25,11 +30,11 @@
     "xspattern": "^3.1.0"
   },
   "devDependencies": {
-    "@conform-ed/contracts": "0.0.17",
-    "@conform-ed/qti-xml": "0.0.17",
+    "@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

@@ -0,0 +1,58 @@
+/**
+ * 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 — every module re-exported here
+ * (./normalized-item, ./item-capability, ./response-processing, ./rp, ./item-score,
+ * ./store, ./test, ./response-validity) is verified framework-light.
+ */
+
+export {
+  assessmentItemViewFromNormalized,
+  assessmentTestViewFromNormalized,
+  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,
+  AssessmentStimulusRefView,
+  BodyNode,
+  InteractionNode,
+  StimulusContentView,
+  XmlContentNode,
+} from "./runtime";
+export type { AssessmentTestView } from "./test";
+export type { Cardinality, ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";

package/src/index.ts

@@ -14,12 +14,16 @@ export {
 
 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";
 
 export {