@conform-ed/qti-react 0.0.17 → 0.0.19

package/src/item-capability.ts

@@ -0,0 +1,211 @@
+/**
+ * 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 { CapabilityIssue, CapabilityReport } from "./capability";
+import { isAllowedFlowElement, v0ContentModel, type ContentModel } from "./content-model";
+import { collectRpIssues, collectTemplateIssues } from "./rp";
+import type {
+  AssessmentItemView,
+  AssessmentStimulusRefView,
+  BodyNode,
+  InteractionNode,
+  StimulusContentView,
+  XmlContentNode,
+} from "./runtime";
+
+const feedbackKinds = new Set(["feedbackInline", "feedbackBlock"]);
+const templateContentKinds = new Set(["templateInline", "templateBlock"]);
+
+/** Body node kinds that render without a descriptor, skin, or content-model entry. */
+const intrinsicLeafKinds = new Set(["text", "printedVariable"]);
+
+function isFeedbackNode(node: BodyNode): boolean {
+  return feedbackKinds.has(node.kind);
+}
+
+function isTemplateContentNode(node: BodyNode): boolean {
+  return templateContentKinds.has(node.kind);
+}
+
+/**
+ * An interaction node is any non-xml node carrying a `responseIdentifier` — including
+ * kinds this runtime has never heard of. The discriminator must not depend on the
+ * supported set, or unknown interactions would be indistinguishable from text.
+ */
+function isInteractionNode(node: BodyNode): node is InteractionNode {
+  return node.kind !== "xml" && typeof (node as { responseIdentifier?: unknown }).responseIdentifier === "string";
+}
+
+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 function reportItemCapability(item: AssessmentItemView, options: ItemCapabilityOptions): CapabilityReport {
+  const model = options.model ?? v0ContentModel;
+  const customOperatorClasses = options.customOperatorClasses ?? new Set<string>();
+  const issues: CapabilityIssue[] = [];
+  const seen = new Set<string>();
+
+  function report(issue: CapabilityIssue): void {
+    const dedupeKey = `${issue.type}:${issue.name}:${issue.responseIdentifier ?? ""}`;
+
+    if (!seen.has(dedupeKey)) {
+      seen.add(dedupeKey);
+      issues.push(issue);
+    }
+  }
+
+  function walk(node: BodyNode): void {
+    if (isFeedbackNode(node) || isTemplateContentNode(node) || node.kind === "rubricBlock") {
+      for (const child of (node as unknown as { content?: readonly BodyNode[] }).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 as XmlContentNode;
+
+      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 };
+}
+
+/**
+ * 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 const referenceInteractionKinds: readonly string[] = [
+  "associateInteraction",
+  "choiceInteraction",
+  "drawingInteraction",
+  "endAttemptInteraction",
+  "extendedTextInteraction",
+  "gapMatchInteraction",
+  "graphicAssociateInteraction",
+  "graphicGapMatchInteraction",
+  "graphicOrderInteraction",
+  "hotspotInteraction",
+  "hottextInteraction",
+  "inlineChoiceInteraction",
+  "matchInteraction",
+  "mediaInteraction",
+  "orderInteraction",
+  "positionObjectStage",
+  "selectPointInteraction",
+  "sliderInteraction",
+  "textEntryInteraction",
+  "uploadInteraction",
+];

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,
+  };
+}

package/src/runtime.ts

@@ -20,7 +20,7 @@ import {
 } from "react";
 import type { ZodType } from "zod";
 
-import type { CapabilityIssue, CapabilityReport } from "./capability";
+import type { CapabilityReport } from "./capability";
 import {
   isAllowedFlowElement,
   sanitizeAttributes,
@@ -28,9 +28,9 @@ import {
   v0ContentModel,
   type ContentModel,
 } from "./content-model";
+import { reportItemCapability } from "./item-capability";
 import { resolveCatalogSupports, type CatalogView, type PnpView, type ResolvedCatalogSupport } from "./pnp";
 import { collectInteractionConstraints } from "./response-validity";
-import { collectRpIssues, collectTemplateIssues } from "./rp";
 import type {
   CustomOperatorImplementation,
   OutcomeDeclarationView,
@@ -391,9 +391,6 @@ function templateVisible(value: OutcomeValue, view: TemplateContentView): boolea
   return matched !== (view.showHide === "hide");
 }
 
-/** Body node kinds that render without a descriptor, skin, or content-model entry. */
-const intrinsicLeafKinds = new Set(["text", "printedVariable"]);
-
 /** A read-only, already-"submitted" store: backs content rendered outside an attempt. */
 function createStaticStore(outcomes: Readonly<Record<string, OutcomeValue>>): AttemptStore {
   const snapshot: AttemptSnapshot = {
@@ -1015,125 +1012,22 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   }
 
   function canDeliver(item: AssessmentItemView): CapabilityReport {
-    const issues: CapabilityIssue[] = [];
-    const seen = new Set<string>();
-
-    function report(issue: CapabilityIssue): void {
-      const dedupeKey = `${issue.type}:${issue.name}:${issue.responseIdentifier ?? ""}`;
-
-      if (!seen.has(dedupeKey)) {
-        seen.add(dedupeKey);
-        issues.push(issue);
-      }
-    }
-
-    function walk(node: BodyNode): void {
-      if (isFeedbackNode(node) || isTemplateContentNode(node) || node.kind === "rubricBlock") {
-        for (const child of (node as unknown as { content?: readonly BodyNode[] }).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 } : {}),
-          });
-        }
-
-        // Interaction-internal content (prompt, choice bodies) is structurally
-        // validated by the descriptor schema; its flow elements are walked when the
-        // descriptor surfaces them. Generic field-sniffing is deliberately avoided.
-        return;
-      }
-
-      if (node.kind === "xml") {
-        const xmlNode = node as XmlContentNode;
-
-        if (xmlNode.name === model.mathRoot) {
-          return; // MathML renders structurally; its subtree is not flow content
-        }
-
-        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;
-      }
-
-      // Any other kind (include, multi-stage groups, future vocabulary) has no
-      // rendering path: report it rather than let the renderer drop it (ADR-0003).
-      report({ type: "unsupported-element", name: node.kind });
-    }
-
-    for (const node of item.itemBody.content ?? []) {
-      walk(node);
-    }
-
-    // Shared stimulus refs must resolve to be deliverable; resolved content passes
-    // through the same content-model gate as the body.
-    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);
-    }
+    // Reduce this runtime's React config to the headless capability inputs: an interaction
+    // is supported when it has both a descriptor and a skin; descriptor schemas drive the
+    // stricter invalid-interaction check. The walk itself lives in ./item-capability so a
+    // server-side caller reaches the same verdict without importing React.
+    const supportedInteractions = new Set([...descriptorsByKind.keys()].filter((kind) => Boolean(config.skin[kind])));
+    const interactionSchemas = new Map(
+      [...descriptorsByKind].map(([kind, descriptor]) => [kind, descriptor.schema] as const),
+    );
 
-    return { deliverable: issues.length === 0, issues };
+    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 };