@conform-ed/pci-math-entry 0.0.13

package/README.md

@@ -0,0 +1,58 @@
+# @conform-ed/pci-math-entry
+
+The reference PCI for the conform-ed QTI stack: math entry with MathLive input and
+compute-engine checking. It exists to be a real, end-to-end example of what a PCI
+package looks like for consumers of `@conform-ed/qti-react` — interaction module,
+pure checker, and response-processing operator, each on its own subpath.
+
+## The response contract
+
+The response of record is a PCI JSON record:
+
+- `expression` — the learner's LaTeX, exactly as written. Always present.
+- `verdict` — an **advisory** boolean computed client-side by the same checker the
+  platform re-scores with. Present only when the item carries checker config
+  (`data-correct`, optional `data-mode`, `data-tolerance`); a high-stakes delivery
+  redacts those properties and the module degrades to expression-only. Unjudgeable
+  input omits the verdict — never a guess.
+
+Items score portably with plain QTI (`qti-field-value` over `verdict`); platforms
+holding the expression re-score it server-side for the authoritative result.
+
+## Subpaths
+
+- `.` — checker, operator, module core (injectable input), type identifier.
+- `./checker` — the pure function only (compute-engine; no qti-react, no DOM).
+- `./operator` — `org.conform-ed.mathEquivalent` for `QtiRuntimeConfig.customOperators`.
+- `./module` — the browser-ready module (MathLive + compute-engine). Heavy by design;
+  load it lazily (ADR-0007: descriptors eager, implementations lazy):
+
+```ts
+const { mathEntryModule } = await import("@conform-ed/pci-math-entry/module");
+registry.registerModule("math-entry", mathEntryModule);
+```
+
+## Checking modes
+
+- `equivalent` (default) — symbolic equality, any mathematically equal form passes;
+  optional absolute `tolerance` for float answers.
+- `literal` — the written form matters (EqualComAss-style: `\frac{2}{4}` and `0.5`
+  fail against `\frac{1}{2}`; reordered terms pass).
+
+## Server-side re-scoring
+
+The checker is a pure function — no adapters, usable from any API:
+
+```ts
+import { checkMathExpression } from "@conform-ed/pci-math-entry/checker";
+
+Bun.serve({
+  port: 3000,
+  fetch: async (request) => {
+    const { expression, correct, mode, tolerance } = await request.json();
+    const result = checkMathExpression(expression, correct, { mode, tolerance });
+
+    return Response.json(result); // { verdict: boolean | null, reason? }
+  },
+});
+```

package/dist/checker.js

@@ -0,0 +1,6 @@
+import {
+  checkMathExpression
+} from "./index-n2b9z4x4.js";
+export {
+  checkMathExpression
+};

package/dist/index-4z8t2fk0.js

@@ -0,0 +1,60 @@
+import {
+  checkMathExpression
+} from "./index-n2b9z4x4.js";
+
+// src/module.ts
+var mathEntryTypeIdentifier = "urn:conform-ed:pci:math-entry";
+function restoredExpression(state) {
+  if (state === undefined || state === "") {
+    return "";
+  }
+  try {
+    const parsed = JSON.parse(state);
+    return typeof parsed.expression === "string" ? parsed.expression : "";
+  } catch {
+    return "";
+  }
+}
+function checkerOptions(properties) {
+  const mode = properties["mode"];
+  const tolerance = Number(properties["tolerance"]);
+  return {
+    ...mode === "equivalent" || mode === "literal" ? { mode } : {},
+    ...properties["tolerance"] !== undefined && Number.isFinite(tolerance) ? { tolerance } : {}
+  };
+}
+function createMathEntryModule(input) {
+  return {
+    typeIdentifier: mathEntryTypeIdentifier,
+    getInstance(dom, configuration, state) {
+      const properties = configuration.properties ?? {};
+      const container = dom.ownerDocument.createElement("div");
+      container.className = "math-entry-pci";
+      dom.appendChild(container);
+      const handle = input(container, { initialLatex: restoredExpression(state) });
+      const instance = {
+        typeIdentifier: mathEntryTypeIdentifier,
+        getResponse() {
+          const latex = handle.getValue().trim();
+          const expressionEntry = latex === "" ? { name: "expression", base: null } : { name: "expression", base: { string: latex } };
+          const correct = properties["correct"];
+          if (latex === "" || correct === undefined) {
+            return { record: [expressionEntry] };
+          }
+          const { verdict } = checkMathExpression(latex, correct, checkerOptions(properties));
+          return verdict === null ? { record: [expressionEntry] } : { record: [expressionEntry, { name: "verdict", base: { boolean: verdict } }] };
+        },
+        getState() {
+          return JSON.stringify({ expression: handle.getValue() });
+        },
+        oncompleted() {
+          handle.destroy?.();
+        }
+      };
+      configuration.onready?.(instance, state);
+      return instance;
+    }
+  };
+}
+
+export { mathEntryTypeIdentifier, createMathEntryModule };

package/dist/index-k2p6zcy8.js

@@ -0,0 +1,35 @@
+import {
+  checkMathExpression
+} from "./index-n2b9z4x4.js";
+
+// src/operator.ts
+var mathEquivalentClass = "org.conform-ed.mathEquivalent";
+function singleString(value) {
+  if (value === null || value.values.length !== 1) {
+    return null;
+  }
+  const member = value.values[0];
+  return typeof member === "string" ? member : typeof member === "number" ? String(member) : null;
+}
+function parseMode(value) {
+  const mode = singleString(value);
+  return mode === "equivalent" || mode === "literal" ? mode : undefined;
+}
+var mathEquivalentOperator = (args) => {
+  const candidate = singleString(args[0] ?? null);
+  const correct = singleString(args[1] ?? null);
+  if (candidate === null || correct === null) {
+    return null;
+  }
+  const mode = parseMode(args[2] ?? null);
+  const toleranceMember = args[3]?.values[0];
+  const tolerance = typeof toleranceMember === "number" ? toleranceMember : undefined;
+  const options = {
+    ...mode === undefined ? {} : { mode },
+    ...tolerance === undefined ? {} : { tolerance }
+  };
+  const result = checkMathExpression(candidate, correct, options);
+  return result.verdict === null ? null : { cardinality: "single", baseType: "boolean", values: [result.verdict] };
+};
+
+export { mathEquivalentClass, mathEquivalentOperator };

package/dist/index-n2b9z4x4.js

@@ -0,0 +1,72 @@
+// src/checker.ts
+import { ComputeEngine } from "@cortex-js/compute-engine";
+var ce = new ComputeEngine;
+function fingerprintRationalLiterals(latex) {
+  return latex.replace(/\\frac\s*\{\s*(-?\d+)\s*\}\s*\{\s*(-?\d+)\s*\}/gu, "\\operatorname{ratlit}($1,$2)").replace(/\\frac\s*(\d)\s*(\d)/gu, "\\operatorname{ratlit}($1,$2)").replace(/(?<![\w.])(-?\d+)\s*\/\s*(\d+)(?![\w.])/gu, "\\operatorname{ratlit}($1,$2)");
+}
+var commutativeHeads = new Set(["Add", "Multiply"]);
+function normalizeOperandOrder(node) {
+  if (!Array.isArray(node)) {
+    return node;
+  }
+  const [head, ...operands] = node;
+  const mapped = operands.map(normalizeOperandOrder);
+  if (typeof head === "string" && commutativeHeads.has(head)) {
+    mapped.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  }
+  return [head, ...mapped];
+}
+function sameJson(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((member, i) => sameJson(member, b[i]));
+  }
+  if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((key) => sameJson(left[key], right[key]));
+  }
+  return a === b;
+}
+function parseLatex(latex, form) {
+  if (latex.trim() === "") {
+    return null;
+  }
+  const expression = ce.parse(latex, { form });
+  return expression.isValid ? expression : null;
+}
+function realValue(expression) {
+  const numeric = expression.N();
+  const real = numeric.re;
+  const imaginary = numeric.im;
+  return Number.isFinite(real) && imaginary === 0 ? real : null;
+}
+function checkMathExpression(candidate, correct, options) {
+  const mode = options?.mode ?? "equivalent";
+  const form = mode === "equivalent" ? "canonical" : "structural";
+  const prepare = mode === "literal" ? fingerprintRationalLiterals : (latex) => latex;
+  const candidateExpression = parseLatex(prepare(candidate), form);
+  if (candidateExpression === null) {
+    return { verdict: null, reason: "candidate-parse-error" };
+  }
+  const correctExpression = parseLatex(prepare(correct), form);
+  if (correctExpression === null) {
+    return { verdict: null, reason: "correct-parse-error" };
+  }
+  if (mode === "literal") {
+    return {
+      verdict: sameJson(normalizeOperandOrder(candidateExpression.json), normalizeOperandOrder(correctExpression.json))
+    };
+  }
+  if (options?.tolerance !== undefined) {
+    const candidateValue = realValue(candidateExpression);
+    const correctValue = realValue(correctExpression);
+    if (candidateValue !== null && correctValue !== null) {
+      return { verdict: Math.abs(candidateValue - correctValue) <= options.tolerance };
+    }
+  }
+  const equal = candidateExpression.isEqual(correctExpression);
+  return equal === undefined ? { verdict: null, reason: "undecidable" } : { verdict: equal };
+}
+
+export { checkMathExpression };

package/dist/index.js

@@ -0,0 +1,18 @@
+import {
+  mathEquivalentClass,
+  mathEquivalentOperator
+} from "./index-k2p6zcy8.js";
+import {
+  createMathEntryModule,
+  mathEntryTypeIdentifier
+} from "./index-4z8t2fk0.js";
+import {
+  checkMathExpression
+} from "./index-n2b9z4x4.js";
+export {
+  mathEquivalentOperator,
+  mathEquivalentClass,
+  mathEntryTypeIdentifier,
+  createMathEntryModule,
+  checkMathExpression
+};

package/dist/module-mathlive.js

@@ -0,0 +1,32 @@
+import {
+  createMathEntryModule,
+  mathEntryTypeIdentifier
+} from "./index-4z8t2fk0.js";
+import"./index-n2b9z4x4.js";
+
+// src/mathlive-input.ts
+import { MathfieldElement } from "mathlive";
+var mathLiveInput = (container, options) => {
+  const field = new MathfieldElement;
+  field.value = options.initialLatex;
+  if (options.disabled === true) {
+    field.readOnly = true;
+  }
+  container.appendChild(field);
+  return {
+    getValue: () => field.value,
+    setValue: (latex) => {
+      field.value = latex;
+    },
+    destroy: () => {
+      field.remove();
+    }
+  };
+};
+
+// src/module-mathlive.ts
+var mathEntryModule = createMathEntryModule(mathLiveInput);
+export {
+  mathEntryTypeIdentifier,
+  mathEntryModule
+};

package/dist/operator.js

@@ -0,0 +1,9 @@
+import {
+  mathEquivalentClass,
+  mathEquivalentOperator
+} from "./index-k2p6zcy8.js";
+import"./index-n2b9z4x4.js";
+export {
+  mathEquivalentOperator,
+  mathEquivalentClass
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@conform-ed/pci-math-entry",
+  "version": "0.0.13",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./checker": {
+      "types": "./src/checker.ts",
+      "import": "./dist/checker.js"
+    },
+    "./operator": {
+      "types": "./src/operator.ts",
+      "import": "./dist/operator.js"
+    },
+    "./module": {
+      "types": "./src/module-mathlive.ts",
+      "import": "./dist/module-mathlive.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts ./src/checker.ts ./src/operator.ts ./src/module-mathlive.ts --outdir dist --format esm --target browser --splitting --external mathlive --external @cortex-js/compute-engine --external @conform-ed/qti-react",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@cortex-js/compute-engine": "^0.59.0",
+    "mathlive": "^0.110.0"
+  },
+  "devDependencies": {
+    "@conform-ed/qti-react": "0.0.13",
+    "happy-dom": "^20.10.2"
+  },
+  "peerDependencies": {
+    "@conform-ed/qti-react": ">=0.0.12"
+  },
+  "peerDependenciesMeta": {
+    "@conform-ed/qti-react": {
+      "optional": true
+    }
+  }
+}

package/src/checker.ts

@@ -0,0 +1,142 @@
+/**
+ * The pure math checker: LaTeX in, verdict out (compute-engine under the hood).
+ * Framework-free and I/O-free by design — the identical function produces the PCI's
+ * advisory client-side verdict and the platform's authoritative re-score, so the two
+ * can only disagree across package versions, never across code paths.
+ *
+ * Modes: "equivalent" accepts any mathematically equal form (symbolic equality with
+ * compute-engine's numeric probing); "literal" compares the non-canonical parse trees,
+ * so the written form matters (\frac{2}{4} ≠ \frac{1}{2}). An absolute `tolerance`
+ * widens numeric comparison in equivalent mode (float answers like the sine-rule item).
+ */
+
+import { ComputeEngine } from "@cortex-js/compute-engine";
+import type { BoxedExpression } from "@cortex-js/compute-engine";
+
+export type MathCheckMode = "equivalent" | "literal";
+
+export interface MathCheckOptions {
+  /** Default "equivalent". */
+  readonly mode?: MathCheckMode;
+  /** Absolute numeric window; only meaningful in equivalent mode. */
+  readonly tolerance?: number;
+}
+
+export type MathCheckReason = "candidate-parse-error" | "correct-parse-error" | "undecidable";
+
+export interface MathCheckResult {
+  /** true/false when judged; null when the input could not be judged at all. */
+  readonly verdict: boolean | null;
+  readonly reason?: MathCheckReason;
+}
+
+const ce = new ComputeEngine();
+
+/**
+ * Literal mode compares the written form, but compute-engine's parser eagerly reduces
+ * rational literals in every mode (\frac{2}{4} parses as 1/2 even non-canonically), so
+ * digit fractions are rewritten to an opaque marker before parsing. The resulting
+ * trees are form fingerprints, not mathematics — they exist only to be compared.
+ */
+function fingerprintRationalLiterals(latex: string): string {
+  return latex
+    .replace(/\\frac\s*\{\s*(-?\d+)\s*\}\s*\{\s*(-?\d+)\s*\}/gu, "\\operatorname{ratlit}($1,$2)")
+    .replace(/\\frac\s*(\d)\s*(\d)/gu, "\\operatorname{ratlit}($1,$2)")
+    .replace(/(?<![\w.])(-?\d+)\s*\/\s*(\d+)(?![\w.])/gu, "\\operatorname{ratlit}($1,$2)");
+}
+
+/**
+ * Literal verdicts are EqualComAss-style (the STACK convention): the written *form*
+ * matters, term order does not — rejecting "1+x" for "x+1" is never the pedagogy.
+ * Operands of commutative heads sort before comparison.
+ */
+const commutativeHeads = new Set(["Add", "Multiply"]);
+
+function normalizeOperandOrder(node: unknown): unknown {
+  if (!Array.isArray(node)) {
+    return node;
+  }
+
+  const [head, ...operands] = node as unknown[];
+  const mapped = operands.map(normalizeOperandOrder);
+
+  if (typeof head === "string" && commutativeHeads.has(head)) {
+    mapped.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  }
+
+  return [head, ...mapped];
+}
+
+/** Structural equality over MathJSON (isSame compares number literals numerically). */
+function sameJson(a: unknown, b: unknown): boolean {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((member, i) => sameJson(member, b[i]))
+    );
+  }
+
+  if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+    const left = a as Record<string, unknown>;
+    const right = b as Record<string, unknown>;
+    const keys = Object.keys(left);
+
+    return keys.length === Object.keys(right).length && keys.every((key) => sameJson(left[key], right[key]));
+  }
+
+  return a === b;
+}
+
+function parseLatex(latex: string, form: "canonical" | "structural"): BoxedExpression | null {
+  if (latex.trim() === "") {
+    return null;
+  }
+
+  const expression = ce.parse(latex, { form });
+
+  return expression.isValid ? expression : null;
+}
+
+/** Finite real value of an expression, or null when it is not plainly numeric. */
+function realValue(expression: BoxedExpression): number | null {
+  const numeric = expression.N();
+  const real = numeric.re;
+  const imaginary = numeric.im;
+
+  return Number.isFinite(real) && imaginary === 0 ? real : null;
+}
+
+export function checkMathExpression(candidate: string, correct: string, options?: MathCheckOptions): MathCheckResult {
+  const mode = options?.mode ?? "equivalent";
+  const form = mode === "equivalent" ? "canonical" : "structural";
+  const prepare = mode === "literal" ? fingerprintRationalLiterals : (latex: string) => latex;
+  const candidateExpression = parseLatex(prepare(candidate), form);
+
+  if (candidateExpression === null) {
+    return { verdict: null, reason: "candidate-parse-error" };
+  }
+
+  const correctExpression = parseLatex(prepare(correct), form);
+
+  if (correctExpression === null) {
+    return { verdict: null, reason: "correct-parse-error" };
+  }
+
+  if (mode === "literal") {
+    return {
+      verdict: sameJson(normalizeOperandOrder(candidateExpression.json), normalizeOperandOrder(correctExpression.json)),
+    };
+  }
+
+  if (options?.tolerance !== undefined) {
+    const candidateValue = realValue(candidateExpression);
+    const correctValue = realValue(correctExpression);
+
+    if (candidateValue !== null && correctValue !== null) {
+      return { verdict: Math.abs(candidateValue - correctValue) <= options.tolerance };
+    }
+  }
+
+  const equal = candidateExpression.isEqual(correctExpression);
+
+  return equal === undefined ? { verdict: null, reason: "undecidable" } : { verdict: equal };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { checkMathExpression } from "./checker";
+export type { MathCheckMode, MathCheckOptions, MathCheckReason, MathCheckResult } from "./checker";
+export { mathEquivalentClass, mathEquivalentOperator } from "./operator";
+export { createMathEntryModule, mathEntryTypeIdentifier } from "./module";
+export type { MathInputFactory, MathInputHandle, MathInputOptions } from "./module";

package/src/mathlive-input.ts

@@ -0,0 +1,32 @@
+/**
+ * The MathLive input adapter: a <math-field> custom element inside the module-owned
+ * container. Importing this file registers the element and pulls MathLive's full
+ * bundle — browser-only and heavy by design; consumers reach it through the ./module
+ * subpath via lazy import() (ADR-0007: descriptors eager, implementations lazy).
+ */
+
+import { MathfieldElement } from "mathlive";
+
+import type { MathInputFactory } from "./module";
+
+export const mathLiveInput: MathInputFactory = (container, options) => {
+  const field = new MathfieldElement();
+
+  field.value = options.initialLatex;
+
+  if (options.disabled === true) {
+    field.readOnly = true;
+  }
+
+  container.appendChild(field);
+
+  return {
+    getValue: () => field.value,
+    setValue: (latex) => {
+      field.value = latex;
+    },
+    destroy: () => {
+      field.remove();
+    },
+  };
+};

package/src/module-mathlive.ts

@@ -0,0 +1,14 @@
+/**
+ * The browser-ready math-entry PCI: MathLive input + checker verdicts. Heavy by
+ * design (MathLive + compute-engine) — load via lazy import() just before an item
+ * using the interaction mounts, and register with the consumer's PCI registry:
+ *
+ *   const { mathEntryModule } = await import("@conform-ed/pci-math-entry/module");
+ *   registry.registerModule("math-entry", mathEntryModule);
+ */
+
+import { mathLiveInput } from "./mathlive-input";
+import { createMathEntryModule } from "./module";
+
+export const mathEntryModule = createMathEntryModule(mathLiveInput);
+export { mathEntryTypeIdentifier } from "./module";

package/src/module.ts

@@ -0,0 +1,113 @@
+/**
+ * The math-entry PCI module (IMS PCI v1 against the qti-react host contract). The
+ * input widget is injected (`MathInputFactory`) so the module core stays testable and
+ * DOM-library-free; the MathLive adapter lives in ./mathlive-input and the bundled
+ * browser module in ./module-mathlive.
+ *
+ * Response of record (design decisions, BACKLOG #1): a PCI JSON record with the
+ * learner's LaTeX `expression` plus an advisory `verdict` computed by the same pure
+ * checker the platform re-scores with. The verdict exists only when the item carries
+ * checker config (`correct`, optional `mode`/`tolerance` properties — authored as
+ * data-* attributes); high-stakes deliveries redact those properties and the module
+ * degrades to expression-only, leaving scoring entirely server-side. An unjudgeable
+ * expression omits the verdict rather than guessing.
+ */
+
+import type { PciConfiguration, PciInstance, PciModule } from "@conform-ed/qti-react";
+
+import { checkMathExpression } from "./checker";
+import type { MathCheckMode, MathCheckOptions } from "./checker";
+
+export const mathEntryTypeIdentifier = "urn:conform-ed:pci:math-entry";
+
+export interface MathInputOptions {
+  readonly initialLatex: string;
+  readonly disabled?: boolean;
+}
+
+export interface MathInputHandle {
+  readonly getValue: () => string;
+  readonly setValue: (latex: string) => void;
+  readonly destroy?: () => void;
+}
+
+/** Creates the actual input widget inside the module-owned container. */
+export type MathInputFactory = (container: Element, options: MathInputOptions) => MathInputHandle;
+
+interface MathEntryState {
+  readonly expression?: string;
+}
+
+function restoredExpression(state: string | undefined): string {
+  if (state === undefined || state === "") {
+    return "";
+  }
+
+  try {
+    const parsed = JSON.parse(state) as MathEntryState;
+
+    return typeof parsed.expression === "string" ? parsed.expression : "";
+  } catch {
+    return "";
+  }
+}
+
+function checkerOptions(properties: Readonly<Record<string, string>>): MathCheckOptions {
+  const mode = properties["mode"];
+  const tolerance = Number(properties["tolerance"]);
+
+  return {
+    ...(mode === "equivalent" || mode === "literal" ? { mode: mode as MathCheckMode } : {}),
+    ...(properties["tolerance"] !== undefined && Number.isFinite(tolerance) ? { tolerance } : {}),
+  };
+}
+
+export function createMathEntryModule(input: MathInputFactory): PciModule {
+  return {
+    typeIdentifier: mathEntryTypeIdentifier,
+
+    getInstance(dom: Element, configuration: PciConfiguration, state: string | undefined): PciInstance {
+      const properties = configuration.properties ?? {};
+      const container = dom.ownerDocument.createElement("div");
+
+      container.className = "math-entry-pci";
+      dom.appendChild(container);
+
+      const handle = input(container, { initialLatex: restoredExpression(state) });
+
+      const instance: PciInstance = {
+        typeIdentifier: mathEntryTypeIdentifier,
+
+        getResponse(): unknown {
+          const latex = handle.getValue().trim();
+          const expressionEntry =
+            latex === "" ? { name: "expression", base: null } : { name: "expression", base: { string: latex } };
+          const correct = properties["correct"];
+
+          if (latex === "" || correct === undefined) {
+            return { record: [expressionEntry] };
+          }
+
+          const { verdict } = checkMathExpression(latex, correct, checkerOptions(properties));
+
+          // A null verdict is unjudgeable input: omit the field, never guess.
+          return verdict === null
+            ? { record: [expressionEntry] }
+            : { record: [expressionEntry, { name: "verdict", base: { boolean: verdict } }] };
+        },
+
+        getState(): string {
+          return JSON.stringify({ expression: handle.getValue() });
+        },
+
+        oncompleted(): void {
+          handle.destroy?.();
+        },
+      };
+
+      configuration.onready?.(instance, state);
+
+      return instance;
+    },
+  };
+}

package/src/operator.ts

@@ -0,0 +1,55 @@
+/**
+ * The math checker exposed to QTI response processing as a `customOperator`
+ * (qti-react extension seam, ADR-0007 vocabulary). Positional arguments, all
+ * authorable as plain `qti-base-value`:
+ *
+ *   1. candidate LaTeX (usually `qti-variable` / `qti-field-value`)
+ *   2. correct LaTeX
+ *   3. optional mode: "equivalent" (default) | "literal"
+ *   4. optional absolute tolerance (float)
+ *
+ * NULL propagates per QTI convention; an unjudgeable verdict is NULL, never a guess.
+ */
+
+import type { CustomOperatorImplementation, MaybeRpValue } from "@conform-ed/qti-react";
+
+import { checkMathExpression } from "./checker";
+import type { MathCheckMode, MathCheckOptions } from "./checker";
+
+export const mathEquivalentClass = "org.conform-ed.mathEquivalent";
+
+function singleString(value: MaybeRpValue): string | null {
+  if (value === null || value.values.length !== 1) {
+    return null;
+  }
+
+  const member = value.values[0];
+
+  return typeof member === "string" ? member : typeof member === "number" ? String(member) : null;
+}
+
+function parseMode(value: MaybeRpValue): MathCheckMode | undefined {
+  const mode = singleString(value);
+
+  return mode === "equivalent" || mode === "literal" ? mode : undefined;
+}
+
+export const mathEquivalentOperator: CustomOperatorImplementation = (args) => {
+  const candidate = singleString(args[0] ?? null);
+  const correct = singleString(args[1] ?? null);
+
+  if (candidate === null || correct === null) {
+    return null;
+  }
+
+  const mode = parseMode(args[2] ?? null);
+  const toleranceMember = args[3]?.values[0];
+  const tolerance = typeof toleranceMember === "number" ? toleranceMember : undefined;
+  const options: MathCheckOptions = {
+    ...(mode === undefined ? {} : { mode }),
+    ...(tolerance === undefined ? {} : { tolerance }),
+  };
+  const result = checkMathExpression(candidate, correct, options);
+
+  return result.verdict === null ? null : { cardinality: "single", baseType: "boolean", values: [result.verdict] };
+};