@longsightgroup/qti3-core 0.10.4 → 0.10.6

package/src/support-evidence.ts

@@ -51,11 +51,16 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
     "tests/browser/player-interaction-sweep.spec.ts",
   ];
   const extras: Partial<Record<QtiInteractionType, string[]>> = {
-    associate: browserKeyboardA11yTests,
+    associate: [
+      ...browserKeyboardA11yTests,
+      "packages/core/src/association-contracts.test.ts",
+      "tests/browser/player-dom-behavior.spec.ts",
+    ],
     choice: ["tests/browser/player-choice.spec.ts", "tests/browser/player-dom-behavior.spec.ts"],
     drawing: ["tests/browser/player-graphic.spec.ts"],
     endAttempt: ["tests/browser/player-dom-behavior.spec.ts", ...browserKeyboardA11yTests],
     extendedText: [
+      "packages/core/src/text-response.test.ts",
       "tests/browser/player-dom-behavior.spec.ts",
       "tests/browser/player-extended-text-xhtml.spec.ts",
     ],
@@ -65,7 +70,10 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
       "tests/browser/player-graphic-gap-match.spec.ts",
       "tests/browser/player-graphic.spec.ts",
     ],
-    graphicOrder: ["tests/browser/player-graphic.spec.ts"],
+    graphicOrder: [
+      "packages/core/src/graphic-image-contracts.test.ts",
+      "tests/browser/player-graphic.spec.ts",
+    ],
     hotspot: ["tests/browser/player-graphic.spec.ts"],
     hottext: ["tests/browser/player-hottext.spec.ts", "tests/browser/player-dom-behavior.spec.ts"],
     inlineChoice: ["tests/browser/player-inline-choice.spec.ts"],
@@ -81,7 +89,10 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
       "tests/browser/player-slider-cross-browser.spec.ts",
       ...browserKeyboardA11yTests,
     ],
-    textEntry: ["tests/browser/player-dom-behavior.spec.ts"],
+    textEntry: [
+      "packages/core/src/text-response.test.ts",
+      "tests/browser/player-dom-behavior.spec.ts",
+    ],
     upload: ["tests/browser/player-dom-behavior.spec.ts"],
   };
   return [...base, ...(extras[interactionType] ?? [])];

package/src/support.ts

@@ -401,20 +401,29 @@ function entry(qtiName: string, interactionType: QtiInteractionType): QtiInterac
     process: true,
     fixtures: interactionSupportFixtures(interactionType),
     tests: interactionSupportTests(interactionType),
+    notes: ["associate", "graphicAssociate", "match", "gapMatch"].includes(interactionType)
+      ? interactionType === "associate" || interactionType === "graphicAssociate"
+        ? "Supports single and multiple unordered pair responses."
+        : "Supports single and multiple directedPair responses."
+      : interactionType === "graphicGapMatch"
+        ? "Requires multiple directedPair responses."
+        : undefined,
   };
 }
 
 function extendedTextInteractionEntry(): QtiInteractionElementSupport {
   return {
     ...entry("qti-extended-text-interaction", "extendedText"),
-    notes: "Supports plain and format=xhtml extended text.",
+    notes:
+      "Supports single, multiple, ordered and numeric record responses; string/integer/float values; min-strings/max-strings; plain, preformatted and string XHTML capture.",
   };
 }
 
 function textEntryInteractionEntry(): QtiInteractionElementSupport {
   return {
     ...entry("qti-text-entry-interaction", "textEntry"),
-    notes: "Supports placeholder-text and pattern-mask on text-entry controls.",
+    notes:
+      "Supports single string/integer/float and numeric record responses, base 2–36, string-identifier, placeholder-text and pattern-mask; text-entry format is plain only.",
   };
 }
 

package/src/text-response.ts

@@ -0,0 +1,106 @@
+import type { QtiInteraction, QtiRecordValue, QtiValue } from "./types.js";
+
+/** Capture text using the interaction's declared response type and authored radix. */
+export function captureQtiTextResponse(interaction: QtiInteraction, text: string): QtiValue {
+  if (interaction.responseCardinality === "record") return numericRecord(text, radix(interaction));
+  if (interaction.responseBaseType === "string") return text;
+  if (text.trim() === "") return null;
+  const record = numericRecord(text, radix(interaction));
+  return interaction.responseBaseType === "integer"
+    ? (record.integerValue ?? null)
+    : (record.floatValue ?? null);
+}
+
+/** Recover editable text, including the original lexical form in a numeric record. */
+export function qtiTextResponseString(value: QtiValue): string {
+  if (value !== null && typeof value === "object") {
+    return !Array.isArray(value) && typeof value.stringValue === "string" ? value.stringValue : "";
+  }
+  return value === null ? "" : String(value);
+}
+
+/** Format a captured scalar in its authored radix, preserving companion and record text. */
+export function formatQtiTextResponse(interaction: QtiInteraction, value: QtiValue): string {
+  const base = radix(interaction);
+  if (typeof value === "number" && Number.isInteger(base) && base >= 2 && base <= 36) {
+    return value.toString(base);
+  }
+  return qtiTextResponseString(value);
+}
+
+function radix(interaction: QtiInteraction): number {
+  return Number(interaction.attributes.base ?? 10);
+}
+
+function numericRecord(text: string, base: number): QtiRecordValue {
+  const empty: QtiRecordValue = {
+    stringValue: text,
+    floatValue: null,
+    integerValue: null,
+    leftDigits: null,
+    rightDigits: null,
+    ndp: null,
+    nsf: null,
+    exponent: null,
+  };
+  if (!Number.isInteger(base) || base < 2 || base > 36) return empty;
+  const normalized = text.trim();
+  const match = (
+    base === 10
+      ? /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/
+      : /^([+-]?)([0-9a-z]*)(?:\.([0-9a-z]*))?$/i
+  ).exec(normalized);
+  if (!match) return empty;
+  const left = match[2] ?? "";
+  const right = match[3] ?? "";
+  const digits = left + right;
+  if (!digits || digits.split("").some((digit) => Number.parseInt(digit, 36) >= base)) return empty;
+  const exponent = match[4] === undefined ? null : Number(match[4]);
+  if (exponent !== null && !Number.isSafeInteger(exponent)) return empty;
+  const ndp = Math.max(0, right.length - (exponent ?? 0));
+  if (!Number.isSafeInteger(ndp)) return empty;
+  const magnitude =
+    (Number.parseInt(left || "0", base) +
+      right
+        .split("")
+        .reduce(
+          (sum, digit, index) => sum + Number.parseInt(digit, base) / base ** (index + 1),
+          0,
+        )) *
+    base ** (exponent ?? 0);
+  const value = base === 10 ? Number(normalized) : match[1] === "-" ? -magnitude : magnitude;
+  if (!Number.isFinite(value)) return empty;
+  const integer =
+    match[3] === undefined && exponent === null && Number.isSafeInteger(value) ? value : null;
+  return {
+    stringValue: text,
+    floatValue: value,
+    integerValue: integer,
+    leftDigits: left.length,
+    rightDigits: right.length,
+    ndp,
+    nsf: digits.replace(/^0+/, "").length || 1,
+    exponent,
+  };
+}
+
+export function isQtiTextResponseRecord(value: QtiValue): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const integerFields = new Set([
+    "integerValue",
+    "leftDigits",
+    "rightDigits",
+    "ndp",
+    "nsf",
+    "exponent",
+  ]);
+  return Object.entries(value).every(([field, entry]) => {
+    if (field === "stringValue") return typeof entry === "string" || entry === null;
+    if (field === "floatValue")
+      return entry === null || (typeof entry === "number" && Number.isFinite(entry));
+    return (
+      integerFields.has(field) &&
+      (entry === null || (typeof entry === "number" && Number.isSafeInteger(entry)))
+    );
+  });
+}

package/src/trusted-item-session.ts

@@ -1,5 +1,5 @@
 import { parseQtiXml } from "./parser.js";
-import { itemExpectsAutomatedScore } from "./item-scoring-expectation.js";
+import { itemExpectsAutomatedScore, itemHasExternalScore } from "./item-scoring-expectation.js";
 import { parseQtiResponseVariables } from "./response-validation.js";
 import { createItemSession, isQtiAttemptStateV1, type QtiItemSession } from "./session.js";
 import type {
@@ -190,6 +190,7 @@ export function runTrustedItemSession(
   }
 
   const shouldScore = input.scoring === "always" || applicationResult.appliedSubmission;
+  const externalScore = itemHasExternalScore(parsedResult.parsed.document.item);
 
   let outcomes = sessionResult.session.serialize().outcomes;
   let state = sessionResult.session.serialize();
@@ -212,7 +213,7 @@ export function runTrustedItemSession(
       scoredResult.scored.state,
       parsedResult.parsed.responseIdentifiers,
     );
-    score = readNumericScore(outcomes.SCORE);
+    score = externalScore ? null : readNumericScore(outcomes.SCORE);
 
     if (scoredResult.scored.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
       return emptyTrustedItemSessionFailure(scoredDiagnostics, {
@@ -241,7 +242,7 @@ export function runTrustedItemSession(
   } else {
     state = stripUndeclaredResponses(state, parsedResult.parsed.responseIdentifiers);
     outcomes = state.outcomes;
-    score = readNumericScore(outcomes.SCORE);
+    score = externalScore ? null : readNumericScore(outcomes.SCORE);
   }
 
   return {

package/src/types.ts

@@ -250,6 +250,8 @@ export interface QtiGapMatchGapSegment {
 }
 
 export interface QtiObjectAsset {
+  /** Attributes of an authored image or picture fallback, when present. */
+  imageAttributes?: Record<string, string> | undefined;
   data?: string | undefined;
   type?: string | undefined;
   width?: string | undefined;

package/src/validation-interactions.ts

@@ -34,10 +34,13 @@ export function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDi
     validateInteractionSharedVocabulary(interaction, diagnostics);
     validateInteractionChoices(interaction, diagnostics);
     validateInteractionChildren(interaction, diagnostics);
+    validateGraphicGapMatchChildren(interaction, diagnostics);
+    validatePositionObjectChildren(interaction, diagnostics);
     validateInteractionRequiredAttributes(interaction, diagnostics);
     validatePortableCustomInteraction(interaction, item, diagnostics);
     validateInteractionLimitAttributes(interaction, diagnostics);
     validatePatternMaskAttribute(interaction, diagnostics);
+    validateTextInteractionContract(interaction, responseDeclarations, diagnostics);
     validateGraphicHotspotObjectDimensions(interaction, diagnostics);
     validateCorrectResponseReferences(
       interaction,
@@ -649,7 +652,7 @@ function allowedInteractionChildren(interaction: QtiInteraction): Set<string> |
     case "order":
       return setOf(common, ["qti-simple-choice"]);
     case "associate":
-      return setOf(common, ["qti-simple-match-set", "qti-simple-associable-choice"]);
+      return setOf(common, ["qti-simple-associable-choice"]);
     case "match":
       return setOf(common, ["qti-simple-match-set"]);
     case "gapMatch":
@@ -659,22 +662,24 @@ function allowedInteractionChildren(interaction: QtiInteraction): Set<string> |
     case "hottext":
       return setOf(common, staticContentNames());
     case "graphicOrder":
-      return setOf(common, ["object", "qti-hotspot-choice"]);
+      return setOf(common, ["object", "img", "picture", "qti-hotspot-choice"]);
     case "graphicAssociate":
-      return setOf(common, ["object", "qti-associable-hotspot"]);
+      return setOf(common, ["object", "img", "picture", "qti-associable-hotspot"]);
     case "graphicGapMatch":
       return setOf(common, [
         "object",
+        "img",
+        "picture",
         "qti-gap-text",
         "qti-gap-img",
         "qti-associable-hotspot",
-        ...staticContentNames(),
       ]);
     case "hotspot":
-      return setOf(common, ["object", "qti-hotspot-choice"]);
+      return setOf(common, ["object", "img", "picture", "qti-hotspot-choice"]);
     case "positionObject":
-      return setOf(common, ["object", "img", "qti-position-object-stage"]);
+      return new Set(["object", "img", "picture"]);
     case "selectPoint":
+      return setOf(common, ["object", "img", "picture"]);
     case "media":
       return setOf(common, ["audio", "video", "object", "img"]);
     case "drawing":
@@ -722,13 +727,12 @@ function expectedResponseShape(
     return { cardinalities: ["ordered"], baseTypes: ["identifier"] };
   }
   if (interaction.type === "associate" || interaction.type === "graphicAssociate") {
-    return { cardinalities: ["multiple"], baseTypes: ["pair", "directedPair"] };
+    return { cardinalities: ["single", "multiple"], baseTypes: ["pair"] };
   }
-  if (
-    interaction.type === "match" ||
-    interaction.type === "gapMatch" ||
-    interaction.type === "graphicGapMatch"
-  ) {
+  if (interaction.type === "match" || interaction.type === "gapMatch") {
+    return { cardinalities: ["single", "multiple"], baseTypes: ["directedPair"] };
+  }
+  if (interaction.type === "graphicGapMatch") {
     return { cardinalities: ["multiple"], baseTypes: ["directedPair"] };
   }
   if (interaction.type === "selectPoint" || interaction.type === "positionObject") {
@@ -740,8 +744,14 @@ function expectedResponseShape(
   if (interaction.type === "upload") {
     return { cardinalities: ["single"], baseTypes: ["file"] };
   }
-  if (interaction.type === "textEntry" || interaction.type === "extendedText") {
-    return { cardinalities: ["single"], baseTypes: ["string"] };
+  if (interaction.type === "textEntry") {
+    return { cardinalities: ["single", "record"], baseTypes: ["string", "integer", "float"] };
+  }
+  if (interaction.type === "extendedText") {
+    return {
+      cardinalities: ["single", "multiple", "ordered", "record"],
+      baseTypes: ["string", "integer", "float"],
+    };
   }
   if (interaction.type === "drawing") return { cardinalities: ["single"], baseTypes: ["file"] };
   if (interaction.type === "portableCustom") {
@@ -780,3 +790,118 @@ function needsChoices(interaction: QtiInteraction): boolean {
     interaction.type === "hotspot"
   );
 }
+
+function validateTextInteractionContract(
+  interaction: QtiInteraction,
+  declarations: ReadonlyMap<string, QtiResponseDeclaration>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "textEntry" && interaction.type !== "extendedText") return;
+  const report = (code: string, message: string) =>
+    diagnostics.push({
+      code,
+      severity: "error",
+      message,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  const base = Number(interaction.attributes.base ?? 10);
+  if (!Number.isInteger(base) || base < 2 || base > 36) {
+    report("interaction.text.base", "Text response base must be an integer from 2 through 36.");
+  }
+  const format = interaction.attributes.format;
+  if (
+    format !== undefined &&
+    format !== "plain" &&
+    !(interaction.type === "extendedText" && format === "preformatted") &&
+    !(
+      interaction.type === "extendedText" &&
+      format === "xhtml" &&
+      interaction.responseBaseType === "string"
+    )
+  ) {
+    report(
+      "interaction.text.format.unsupported",
+      `Text format ${format} is not supported; use plain text.`,
+    );
+  }
+  if (interaction.type === "extendedText") {
+    const container =
+      interaction.responseCardinality === "multiple" ||
+      interaction.responseCardinality === "ordered";
+    const max = interaction.attributes["max-strings"];
+    const min = interaction.attributes["min-strings"] ?? "0";
+    if (
+      (container && max === undefined) ||
+      (max !== undefined && !isNonNegativeInteger(max)) ||
+      !isNonNegativeInteger(min) ||
+      Number(min) > (container ? Number(max) : 1)
+    ) {
+      report(
+        "interaction.text.strings",
+        "Extended text requires valid min-strings/max-strings limits; containers require max-strings and the minimum must not exceed the maximum.",
+      );
+    }
+  }
+  const companion = interaction.attributes["string-identifier"];
+  if (companion !== undefined) {
+    const declaration = declarations.get(companion);
+    if (
+      !declaration ||
+      declaration.baseType !== "string" ||
+      declaration.cardinality !== interaction.responseCardinality ||
+      companion === interaction.responseIdentifier ||
+      (interaction.responseBaseType !== "integer" && interaction.responseBaseType !== "float")
+    ) {
+      report(
+        "interaction.text.stringIdentifier",
+        "string-identifier must reference a separate string response with matching cardinality for a numeric text interaction.",
+      );
+    }
+  }
+}
+
+function validateGraphicGapMatchChildren(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "graphicGapMatch") return;
+  const names = interaction.childElements.map((child) => child.qtiName);
+  const sequence = names.join(" ");
+  if (
+    /^(?:qti-prompt )?(?:object|img|picture)(?: qti-gap-(?:text|img))+(?: qti-associable-hotspot)+$/.test(
+      sequence,
+    )
+  )
+    return;
+  diagnostics.push({
+    code: "interaction.graphicGapMatch.children",
+    severity: "error",
+    message:
+      "Graphic Gap Match requires an optional prompt, one image, gap choices, then one or more associable hotspots, in that order.",
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}
+
+function validatePositionObjectChildren(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "positionObject") return;
+  const [child] = interaction.childElements;
+  if (
+    interaction.childElements.length === 1 &&
+    child &&
+    ["object", "img", "picture"].includes(child.qtiName)
+  )
+    return;
+  diagnostics.push({
+    code: "interaction.positionObject.children",
+    severity: "error",
+    message:
+      "Position Object requires exactly one marker image (object, img, or picture); instructions belong before its stage.",
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}