@conform-ed/pci-math-entry 0.0.13 → 0.0.14

package/dist/checker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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).
+ */
+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;
+}
+export declare function checkMathExpression(candidate: string, correct: string, options?: MathCheckOptions): MathCheckResult;

package/dist/index.d.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/dist/mathlive-input.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 type { MathInputFactory } from "./module";
+export declare const mathLiveInput: MathInputFactory;

package/dist/module-mathlive.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 type { PciModule } from "@conform-ed/qti-react";
+export declare const mathEntryModule: PciModule;
+export { mathEntryTypeIdentifier } from "./module";

package/dist/module.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { PciModule } from "@conform-ed/qti-react";
+export declare 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;
+export declare function createMathEntryModule(input: MathInputFactory): PciModule;

package/dist/operator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 } from "@conform-ed/qti-react";
+export declare const mathEquivalentClass = "org.conform-ed.mathEquivalent";
+export declare const mathEquivalentOperator: CustomOperatorImplementation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conform-ed/pci-math-entry",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "files": [
     "src",
     "dist"
@@ -9,35 +9,35 @@
   "module": "src/index.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./checker": {
-      "types": "./src/checker.ts",
+      "types": "./dist/checker.d.ts",
       "import": "./dist/checker.js"
     },
     "./operator": {
-      "types": "./src/operator.ts",
+      "types": "./dist/operator.d.ts",
       "import": "./dist/operator.js"
     },
     "./module": {
-      "types": "./src/module-mathlive.ts",
+      "types": "./dist/module-mathlive.d.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 .",
+    "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 && tsgo -p tsconfig.build.json",
     "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
-    "test": "bun test"
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
     "@cortex-js/compute-engine": "^0.59.0",
     "mathlive": "^0.110.0"
   },
   "devDependencies": {
-    "@conform-ed/qti-react": "0.0.13",
+    "@conform-ed/qti-react": "0.0.14",
     "happy-dom": "^20.10.2"
   },
   "peerDependencies": {

package/src/checker.ts

@@ -11,7 +11,7 @@
  */
 
 import { ComputeEngine } from "@cortex-js/compute-engine";
-import type { BoxedExpression } from "@cortex-js/compute-engine";
+import type { Expression } from "@cortex-js/compute-engine";
 
 export type MathCheckMode = "equivalent" | "literal";
 
@@ -86,7 +86,7 @@ function sameJson(a: unknown, b: unknown): boolean {
   return a === b;
 }
 
-function parseLatex(latex: string, form: "canonical" | "structural"): BoxedExpression | null {
+function parseLatex(latex: string, form: "canonical" | "structural"): Expression | null {
   if (latex.trim() === "") {
     return null;
   }
@@ -97,7 +97,7 @@ function parseLatex(latex: string, form: "canonical" | "structural"): BoxedExpre
 }
 
 /** Finite real value of an expression, or null when it is not plainly numeric. */
-function realValue(expression: BoxedExpression): number | null {
+function realValue(expression: Expression): number | null {
   const numeric = expression.N();
   const real = numeric.re;
   const imaginary = numeric.im;

package/src/module-mathlive.ts

@@ -7,8 +7,10 @@
  *   registry.registerModule("math-entry", mathEntryModule);
  */
 
+import type { PciModule } from "@conform-ed/qti-react";
+
 import { mathLiveInput } from "./mathlive-input";
 import { createMathEntryModule } from "./module";
 
-export const mathEntryModule = createMathEntryModule(mathLiveInput);
+export const mathEntryModule: PciModule = createMathEntryModule(mathLiveInput);
 export { mathEntryTypeIdentifier } from "./module";