@conform-ed/qti-react 0.0.12

package/dist/index.js

@@ -0,0 +1,403 @@
+// src/content-model.ts
+var v0InteractionKinds = ["choiceInteraction", "textEntryInteraction", "inlineChoiceInteraction"];
+var v0FlowElements = new Set([
+  "p",
+  "span",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "br",
+  "ul",
+  "ol",
+  "li",
+  "ruby",
+  "rt",
+  "rp"
+]);
+var v0MathRoot = "math";
+var v0GlobalAttributes = new Set(["id", "class", "lang", "xml:lang", "dir"]);
+var v0ContentModel = {
+  interactionKinds: new Set(v0InteractionKinds),
+  flowElements: v0FlowElements,
+  mathRoot: v0MathRoot,
+  globalAttributes: v0GlobalAttributes
+};
+function isAllowedFlowElement(model, name) {
+  return model.flowElements.has(name) || name === model.mathRoot;
+}
+function isInteractionKind(model, kind) {
+  return model.interactionKinds.has(kind);
+}
+function isUnsafeAttribute(name, value) {
+  const lowerName = name.toLowerCase();
+  if (lowerName.startsWith("on")) {
+    return true;
+  }
+  if (typeof value === "string" && /^\s*javascript:/iu.test(value)) {
+    return true;
+  }
+  return false;
+}
+function sanitizeAttributes(model, attributes) {
+  const safe = {};
+  if (!attributes) {
+    return safe;
+  }
+  for (const [name, value] of Object.entries(attributes)) {
+    if (isUnsafeAttribute(name, value)) {
+      continue;
+    }
+    if (!model.globalAttributes.has(name)) {
+      continue;
+    }
+    if (typeof value === "string") {
+      safe[name] = value;
+    }
+  }
+  return safe;
+}
+// src/response-processing.ts
+function foldString(value) {
+  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLocaleLowerCase();
+}
+function asList(response) {
+  if (response === null) {
+    return [];
+  }
+  return typeof response === "string" ? [response] : [...response];
+}
+function isStringBaseType(declaration) {
+  return declaration.baseType === "string" || declaration.baseType === undefined;
+}
+function valuesEqual(a, b, fold) {
+  return fold ? foldString(a) === foldString(b) : a === b;
+}
+function matchCorrect(declaration, response) {
+  const correct = declaration.correctResponse;
+  if (!correct) {
+    return false;
+  }
+  const fold = isStringBaseType(declaration);
+  const expected = correct.values.map((entry) => entry.value);
+  const actual = asList(response);
+  if (expected.length !== actual.length) {
+    return false;
+  }
+  if (declaration.cardinality === "ordered") {
+    return expected.every((value, index) => valuesEqual(value, actual[index] ?? "", fold));
+  }
+  const remaining = [...actual];
+  for (const value of expected) {
+    const matchIndex = remaining.findIndex((candidate) => valuesEqual(candidate, value, fold));
+    if (matchIndex === -1) {
+      return false;
+    }
+    remaining.splice(matchIndex, 1);
+  }
+  return remaining.length === 0;
+}
+function clamp(value, lower, upper) {
+  let result = value;
+  if (lower !== undefined && result < lower) {
+    result = lower;
+  }
+  if (upper !== undefined && result > upper) {
+    result = upper;
+  }
+  return result;
+}
+function mapResponse(declaration, response) {
+  const mapping = declaration.mapping;
+  if (!mapping) {
+    return 0;
+  }
+  const defaultValue = mapping.defaultValue ?? 0;
+  let total = 0;
+  for (const member of asList(response)) {
+    const entry = mapping.mapEntries.find((candidate) => valuesEqual(candidate.mapKey, member, !candidate.caseSensitive));
+    total += entry ? entry.mappedValue : defaultValue;
+  }
+  return clamp(total, mapping.lowerBound, mapping.upperBound);
+}
+function scoreResponse(declaration, response) {
+  if (declaration.mapping) {
+    const score = mapResponse(declaration, response);
+    const positiveSum = declaration.mapping.mapEntries.reduce((sum, entry) => sum + Math.max(entry.mappedValue, 0), 0);
+    const maxScore = declaration.mapping.upperBound ?? positiveSum;
+    return {
+      identifier: declaration.identifier,
+      score,
+      maxScore,
+      correct: maxScore > 0 && score >= maxScore
+    };
+  }
+  const correct = matchCorrect(declaration, response);
+  return {
+    identifier: declaration.identifier,
+    score: correct ? 1 : 0,
+    maxScore: 1,
+    correct
+  };
+}
+// src/store.ts
+function createAttemptStore(declarations, initialResponses) {
+  const declarationsById = new Map(declarations.map((declaration) => [declaration.identifier, declaration]));
+  const listeners = new Set;
+  let snapshot = {
+    responses: { ...initialResponses },
+    submitted: false,
+    scores: []
+  };
+  function emit(next) {
+    snapshot = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function computeScores(responses) {
+    return [...declarationsById.values()].map((declaration) => scoreResponse(declaration, responses[declaration.identifier] ?? null));
+  }
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setResponse: (responseIdentifier, value) => {
+      if (snapshot.submitted) {
+        return;
+      }
+      emit({
+        ...snapshot,
+        responses: { ...snapshot.responses, [responseIdentifier]: value }
+      });
+    },
+    submit: () => {
+      const scores = computeScores(snapshot.responses);
+      emit({ ...snapshot, submitted: true, scores });
+      return scores;
+    },
+    reset: () => {
+      emit({ responses: { ...initialResponses }, submitted: false, scores: [] });
+    }
+  };
+}
+// src/runtime.ts
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  useSyncExternalStore
+} from "react";
+function defineInteraction(descriptor) {
+  return descriptor;
+}
+var RuntimeContext = createContext(null);
+function useRuntimeContext() {
+  const context = useContext(RuntimeContext);
+  if (!context) {
+    throw new Error("QTI runtime components must be rendered inside an <ItemRenderer>.");
+  }
+  return context;
+}
+function responseIncludes(value, optionIdentifier) {
+  if (value === null) {
+    return false;
+  }
+  return typeof value === "string" ? value === optionIdentifier : value.includes(optionIdentifier);
+}
+function isCorrectOption(declaration, optionIdentifier) {
+  return Boolean(declaration?.correctResponse?.values.some((entry) => entry.value === optionIdentifier));
+}
+function createQtiRuntime(config) {
+  const model = config.contentModel ?? v0ContentModel;
+  const descriptorsByKind = new Map(config.interactions.map((descriptor) => [descriptor.kind, descriptor]));
+  function renderFlow(node, key) {
+    const isMath = node.name === model.mathRoot;
+    if (!isMath && !isAllowedFlowElement(model, node.name)) {
+      return null;
+    }
+    const attributes = sanitizeAttributes(model, node.attributes);
+    const children = node.children?.map((child, index) => renderNode(child, index));
+    return createElement(node.name, { key, ...attributes }, node.value ?? children);
+  }
+  function renderNode(node, key) {
+    if (isInteractionKind(model, node.kind) && descriptorsByKind.has(node.kind) && config.skin[node.kind]) {
+      return createElement(InteractionHost, { key, node });
+    }
+    if (node.kind === "xml") {
+      return renderFlow(node, key);
+    }
+    const value = node.value;
+    return typeof value === "string" ? value : null;
+  }
+  function InteractionHost({ node }) {
+    const { store, declarationsById } = useRuntimeContext();
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    const responseIdentifier = node.responseIdentifier;
+    const declaration = declarationsById.get(responseIdentifier);
+    const cardinality = declaration?.cardinality ?? "single";
+    const value = snapshot.responses[responseIdentifier] ?? null;
+    const disabled = snapshot.submitted;
+    const answered = value !== null && !(typeof value === "string" && value.trim() === "") && !(Array.isArray(value) && value.length === 0);
+    let status = answered ? "answered" : "unanswered";
+    if (disabled) {
+      const scored = snapshot.scores.find((score) => score.identifier === responseIdentifier);
+      status = scored?.correct ? "correct" : "incorrect";
+    }
+    const setValue = (next) => {
+      store.setResponse(responseIdentifier, next);
+    };
+    const getOptionProps = (optionIdentifier) => {
+      const selected = responseIncludes(value, optionIdentifier);
+      let status2 = selected ? "selected" : "idle";
+      if (disabled) {
+        if (isCorrectOption(declaration, optionIdentifier)) {
+          status2 = "correct";
+        } else if (selected) {
+          status2 = "incorrect";
+        } else {
+          status2 = "idle";
+        }
+      }
+      return {
+        role: cardinality === "single" ? "radio" : "checkbox",
+        tabIndex: 0,
+        "aria-checked": selected,
+        "aria-disabled": disabled,
+        "data-status": status2,
+        onClick: () => {
+          if (disabled) {
+            return;
+          }
+          if (cardinality === "single") {
+            setValue(optionIdentifier);
+            return;
+          }
+          const current = value === null ? [] : typeof value === "string" ? [value] : [...value];
+          const next = selected ? current.filter((entry) => entry !== optionIdentifier) : [...current, optionIdentifier];
+          setValue(next);
+        }
+      };
+    };
+    const renderContent = (nodes) => nodes ? nodes.map((child, index) => renderNode(child, index)) : null;
+    const Skin = config.skin[node.kind];
+    if (!Skin) {
+      return null;
+    }
+    return createElement(Skin, {
+      node,
+      responseIdentifier,
+      value,
+      setValue,
+      disabled,
+      showFeedback: disabled,
+      status,
+      getOptionProps,
+      renderContent
+    });
+  }
+  function ItemRenderer({ item, children }) {
+    const store = useMemo(() => {
+      const initial = {};
+      for (const node of item.itemBody.content ?? []) {}
+      return createAttemptStore(item.responseDeclarations, initial);
+    }, [item]);
+    const declarationsById = useMemo(() => new Map(item.responseDeclarations.map((declaration) => [declaration.identifier, declaration])), [item]);
+    const body = (item.itemBody.content ?? []).map((node, index) => renderNode(node, index));
+    return createElement(RuntimeContext.Provider, { value: { store, declarationsById } }, body, children);
+  }
+  function useAttempt() {
+    const { store } = useRuntimeContext();
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return {
+      ...snapshot,
+      submit: store.submit,
+      reset: store.reset
+    };
+  }
+  return { ItemRenderer, useAttempt };
+}
+// src/interactions/choice.ts
+import { z } from "zod";
+var choiceInteractionNodeSchema = z.object({
+  kind: z.literal("choiceInteraction"),
+  responseIdentifier: z.string().min(1),
+  simpleChoices: z.array(z.object({ identifier: z.string().min(1) })).min(1),
+  maxChoices: z.number().int().optional()
+});
+var choiceInteraction = defineInteraction({
+  kind: "choiceInteraction",
+  schema: choiceInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse() {
+    return null;
+  }
+});
+
+// src/interactions/inline-choice.ts
+import { z as z2 } from "zod";
+var inlineChoiceInteractionNodeSchema = z2.object({
+  kind: z2.literal("inlineChoiceInteraction"),
+  responseIdentifier: z2.string().min(1),
+  inlineChoices: z2.array(z2.object({ identifier: z2.string().min(1) })).min(1)
+});
+var inlineChoiceInteraction = defineInteraction({
+  kind: "inlineChoiceInteraction",
+  schema: inlineChoiceInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse() {
+    return null;
+  }
+});
+
+// src/interactions/text-entry.ts
+import { z as z3 } from "zod";
+var textEntryInteractionNodeSchema = z3.object({
+  kind: z3.literal("textEntryInteraction"),
+  responseIdentifier: z3.string().min(1),
+  expectedLength: z3.number().int().optional(),
+  placeholderText: z3.string().optional(),
+  patternMask: z3.string().optional()
+});
+var textEntryInteraction = defineInteraction({
+  kind: "textEntryInteraction",
+  schema: textEntryInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse() {
+    return null;
+  }
+});
+
+// src/interactions/index.ts
+var qtiCoreInteractions = [
+  choiceInteraction,
+  textEntryInteraction,
+  inlineChoiceInteraction
+];
+
+// src/index.ts
+var qtiReactPackageName = "@conform-ed/qti-react";
+export {
+  v0InteractionKinds,
+  v0ContentModel,
+  textEntryInteraction,
+  scoreResponse,
+  sanitizeAttributes,
+  qtiReactPackageName,
+  qtiCoreInteractions,
+  matchCorrect,
+  mapResponse,
+  isInteractionKind,
+  isAllowedFlowElement,
+  inlineChoiceInteraction,
+  foldString,
+  defineInteraction,
+  createQtiRuntime,
+  createAttemptStore,
+  choiceInteraction
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@conform-ed/qti-react",
+  "version": "0.0.12",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --external react --external react-dom --external zod",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19",
+    "react": "^19.2.7",
+    "react-dom": "^19"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "zod": ">=4.4.0"
+  }
+}

package/src/content-model.ts

@@ -0,0 +1,115 @@
+/**
+ * The single source of truth for what may appear inside an item/stimulus body.
+ *
+ * Both the renderer's allowlist tree-walk and (later) the authoring editor schema
+ * derive from this definition. QTI 3 bodies are validated for *structure* by
+ * `@conform-ed/contracts`, but their embedded HTML flow content is modelled as a
+ * generic node tree — so validation does not sanitize. This allowlist is the
+ * sanitizer: the renderer emits React only for elements/attributes named here and
+ * drops everything else. It never injects HTML strings.
+ *
+ * v0 scope: the minimal flow/inline vocabulary plus the language-critical bits
+ * (ruby/furigana, MathML). It grows incrementally with the renderer — never "all of
+ * HTML5 at once".
+ */
+
+/** Interaction node kinds the v0 runtime can render. */
+export const v0InteractionKinds = ["choiceInteraction", "textEntryInteraction", "inlineChoiceInteraction"] as const;
+
+export type V0InteractionKind = (typeof v0InteractionKinds)[number];
+
+/** Allowed HTML flow/inline element names for generic `kind: "xml"` body nodes. */
+const v0FlowElements = new Set<string>([
+  "p",
+  "span",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "br",
+  "ul",
+  "ol",
+  "li",
+  // language-critical
+  "ruby",
+  "rt",
+  "rp",
+]);
+
+/**
+ * The MathML root. Its subtree is rendered structurally (presentation MathML) with the
+ * same attribute hardening, but element names inside are not individually allowlisted
+ * in v0 — MathML has no scripting surface once event-handler attributes are stripped.
+ */
+const v0MathRoot = "math";
+
+/** Globally safe attribute names. Everything else (notably `on*`, `style`) is dropped. */
+const v0GlobalAttributes = new Set<string>(["id", "class", "lang", "xml:lang", "dir"]);
+
+export interface ContentModel {
+  readonly interactionKinds: ReadonlySet<string>;
+  readonly flowElements: ReadonlySet<string>;
+  readonly mathRoot: string;
+  readonly globalAttributes: ReadonlySet<string>;
+}
+
+export const v0ContentModel: ContentModel = {
+  interactionKinds: new Set<string>(v0InteractionKinds),
+  flowElements: v0FlowElements,
+  mathRoot: v0MathRoot,
+  globalAttributes: v0GlobalAttributes,
+};
+
+export function isAllowedFlowElement(model: ContentModel, name: string): boolean {
+  return model.flowElements.has(name) || name === model.mathRoot;
+}
+
+export function isInteractionKind(model: ContentModel, kind: string): boolean {
+  return model.interactionKinds.has(kind);
+}
+
+/** True for an attribute name/value pair that must never reach the DOM. */
+function isUnsafeAttribute(name: string, value: unknown): boolean {
+  const lowerName = name.toLowerCase();
+
+  if (lowerName.startsWith("on")) {
+    return true;
+  }
+
+  if (typeof value === "string" && /^\s*javascript:/iu.test(value)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Reduce a raw attribute bag to the safe, allowlisted subset. Used by the body walk so
+ * a node that validates against QTI structure still cannot carry script or handlers.
+ */
+export function sanitizeAttributes(
+  model: ContentModel,
+  attributes: Record<string, unknown> | undefined,
+): Record<string, string> {
+  const safe: Record<string, string> = {};
+
+  if (!attributes) {
+    return safe;
+  }
+
+  for (const [name, value] of Object.entries(attributes)) {
+    if (isUnsafeAttribute(name, value)) {
+      continue;
+    }
+
+    if (!model.globalAttributes.has(name)) {
+      continue;
+    }
+
+    if (typeof value === "string") {
+      safe[name] = value;
+    }
+  }
+
+  return safe;
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+// @conform-ed/qti-react — headless QTI 3 runtime (MIT). No Mantine; React + contracts only.
+
+export const qtiReactPackageName = "@conform-ed/qti-react";
+
+export {
+  v0ContentModel,
+  v0InteractionKinds,
+  isAllowedFlowElement,
+  isInteractionKind,
+  sanitizeAttributes,
+  type ContentModel,
+  type V0InteractionKind,
+} from "./content-model";
+
+export { foldString, mapResponse, matchCorrect, scoreResponse } from "./response-processing";
+
+export { createAttemptStore, type AttemptSnapshot, type AttemptStore } from "./store";
+
+export {
+  createQtiRuntime,
+  defineInteraction,
+  type AssessmentItemView,
+  type AttemptController,
+  type BodyNode,
+  type InteractionDescriptor,
+  type InteractionNode,
+  type InteractionRenderProps,
+  type InteractionSkin,
+  type InteractionStatus,
+  type ItemRendererProps,
+  type OptionProps,
+  type OptionStatus,
+  type QtiRuntime,
+  type QtiRuntimeConfig,
+  type SkinRegistry,
+  type XmlContentNode,
+} from "./runtime";
+
+export { choiceInteraction, inlineChoiceInteraction, qtiCoreInteractions, textEntryInteraction } from "./interactions";
+
+export type {
+  Cardinality,
+  CorrectResponseView,
+  MapEntryView,
+  MappingView,
+  ResponseDeclarationView,
+  ResponseValue,
+  ScoreResult,
+} from "./types";

package/src/interactions/choice.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+/** Minimal node shape the runtime/skin rely on; whole-item validation uses the contract. */
+const choiceInteractionNodeSchema = z.object({
+  kind: z.literal("choiceInteraction"),
+  responseIdentifier: z.string().min(1),
+  simpleChoices: z.array(z.object({ identifier: z.string().min(1) })).min(1),
+  maxChoices: z.number().int().optional(),
+});
+
+export const choiceInteraction = defineInteraction({
+  kind: "choiceInteraction",
+  schema: choiceInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});

package/src/interactions/index.ts

@@ -0,0 +1,16 @@
+import type { InteractionDescriptor } from "../runtime";
+
+import { choiceInteraction } from "./choice";
+import { inlineChoiceInteraction } from "./inline-choice";
+import { textEntryInteraction } from "./text-entry";
+
+export { choiceInteraction } from "./choice";
+export { inlineChoiceInteraction } from "./inline-choice";
+export { textEntryInteraction } from "./text-entry";
+
+/** The v0 interaction set conform-ed ships; emergent assembles these plus its extensions. */
+export const qtiCoreInteractions: readonly InteractionDescriptor[] = [
+  choiceInteraction,
+  textEntryInteraction,
+  inlineChoiceInteraction,
+];

package/src/interactions/inline-choice.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+const inlineChoiceInteractionNodeSchema = z.object({
+  kind: z.literal("inlineChoiceInteraction"),
+  responseIdentifier: z.string().min(1),
+  inlineChoices: z.array(z.object({ identifier: z.string().min(1) })).min(1),
+});
+
+export const inlineChoiceInteraction = defineInteraction({
+  kind: "inlineChoiceInteraction",
+  schema: inlineChoiceInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});

package/src/interactions/text-entry.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+const textEntryInteractionNodeSchema = z.object({
+  kind: z.literal("textEntryInteraction"),
+  responseIdentifier: z.string().min(1),
+  expectedLength: z.number().int().optional(),
+  placeholderText: z.string().optional(),
+  patternMask: z.string().optional(),
+});
+
+export const textEntryInteraction = defineInteraction({
+  kind: "textEntryInteraction",
+  schema: textEntryInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});

package/src/response-processing.ts

@@ -0,0 +1,144 @@
+/**
+ * Client-side response processing for the v0 standard scoring templates.
+ *
+ * Implements `match_correct` and `map_response` (QTI's two standard RP templates),
+ * which cover the v0 interactions (choice, textEntry, inlineChoice). Pure functions:
+ * deterministic given (declaration, response), so scoring is replayable and runs
+ * fully offline in the headless core (ADR-0003 / ADR-0006).
+ */
+
+import type { ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+
+/** Lowercase + strip combining diacritics, for non-case/accent-sensitive comparison. */
+export function foldString(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLocaleLowerCase();
+}
+
+function asList(response: ResponseValue): string[] {
+  if (response === null) {
+    return [];
+  }
+
+  return typeof response === "string" ? [response] : [...response];
+}
+
+function isStringBaseType(declaration: ResponseDeclarationView): boolean {
+  return declaration.baseType === "string" || declaration.baseType === undefined;
+}
+
+function valuesEqual(a: string, b: string, fold: boolean): boolean {
+  return fold ? foldString(a) === foldString(b) : a === b;
+}
+
+/**
+ * `match_correct`: true when the response exactly matches `correctResponse`, respecting
+ * cardinality. String base types fold case/diacritics (textEntry friendliness);
+ * identifier base types compare exactly. Returns false when no correctResponse exists.
+ */
+export function matchCorrect(declaration: ResponseDeclarationView, response: ResponseValue): boolean {
+  const correct = declaration.correctResponse;
+
+  if (!correct) {
+    return false;
+  }
+
+  const fold = isStringBaseType(declaration);
+  const expected = correct.values.map((entry) => entry.value);
+  const actual = asList(response);
+
+  if (expected.length !== actual.length) {
+    return false;
+  }
+
+  if (declaration.cardinality === "ordered") {
+    return expected.every((value, index) => valuesEqual(value, actual[index] ?? "", fold));
+  }
+
+  // single + multiple: order-independent set match
+  const remaining = [...actual];
+
+  for (const value of expected) {
+    const matchIndex = remaining.findIndex((candidate) => valuesEqual(candidate, value, fold));
+
+    if (matchIndex === -1) {
+      return false;
+    }
+
+    remaining.splice(matchIndex, 1);
+  }
+
+  return remaining.length === 0;
+}
+
+function clamp(value: number, lower: number | undefined, upper: number | undefined): number {
+  let result = value;
+
+  if (lower !== undefined && result < lower) {
+    result = lower;
+  }
+
+  if (upper !== undefined && result > upper) {
+    result = upper;
+  }
+
+  return result;
+}
+
+/**
+ * `map_response`: sum the mapped values of the response's members, each member mapped at
+ * most once. Honors per-entry `caseSensitive` (default: case/diacritic-insensitive),
+ * applies the mapping's `defaultValue` to unmatched members, and clamps to
+ * [lowerBound, upperBound]. Returns 0 when no mapping exists.
+ */
+export function mapResponse(declaration: ResponseDeclarationView, response: ResponseValue): number {
+  const mapping = declaration.mapping;
+
+  if (!mapping) {
+    return 0;
+  }
+
+  const defaultValue = mapping.defaultValue ?? 0;
+  let total = 0;
+
+  for (const member of asList(response)) {
+    const entry = mapping.mapEntries.find((candidate) =>
+      valuesEqual(candidate.mapKey, member, !candidate.caseSensitive),
+    );
+
+    total += entry ? entry.mappedValue : defaultValue;
+  }
+
+  return clamp(total, mapping.lowerBound, mapping.upperBound);
+}
+
+/**
+ * Apply the appropriate standard template: `map_response` when a mapping is declared,
+ * otherwise `match_correct`. `maxScore` is the mapping upper bound (or the sum of
+ * positive mapped values) for mapped items, else 1 for match_correct.
+ */
+export function scoreResponse(declaration: ResponseDeclarationView, response: ResponseValue): ScoreResult {
+  if (declaration.mapping) {
+    const score = mapResponse(declaration, response);
+    const positiveSum = declaration.mapping.mapEntries.reduce((sum, entry) => sum + Math.max(entry.mappedValue, 0), 0);
+    const maxScore = declaration.mapping.upperBound ?? positiveSum;
+
+    return {
+      identifier: declaration.identifier,
+      score,
+      maxScore,
+      correct: maxScore > 0 && score >= maxScore,
+    };
+  }
+
+  const correct = matchCorrect(declaration, response);
+
+  return {
+    identifier: declaration.identifier,
+    score: correct ? 1 : 0,
+    maxScore: 1,
+    correct,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,315 @@
+/**
+ * The headless runtime (ADR-0002): a factory that assembles a QTI item renderer from an
+ * injected set of interaction descriptors plus a skin registry. The kind-union is the
+ * injected set — no global registry, no module augmentation. The core owns response
+ * state and a11y wiring; skins are controlled components.
+ *
+ * No Mantine, and no JSX — flow content and skins are composed with `createElement` so
+ * the package needs no JSX build step.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import type { ZodType } from "zod";
+
+import {
+  isAllowedFlowElement,
+  isInteractionKind,
+  sanitizeAttributes,
+  v0ContentModel,
+  type ContentModel,
+} from "./content-model";
+import { createAttemptStore, type AttemptSnapshot, type AttemptStore } from "./store";
+import type { Cardinality, ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+
+// ---------- Node views (structural; validated upstream by @conform-ed/contracts) ----------
+
+export interface XmlContentNode {
+  kind: "xml";
+  name: string;
+  value?: string;
+  attributes?: Record<string, unknown>;
+  children?: BodyNode[];
+}
+
+export interface InteractionNode {
+  kind: string;
+  responseIdentifier: string;
+  [field: string]: unknown;
+}
+
+export type BodyNode = XmlContentNode | InteractionNode | { kind: string; value?: string; children?: BodyNode[] };
+
+export interface AssessmentItemView {
+  responseDeclarations: readonly ResponseDeclarationView[];
+  itemBody: { content?: BodyNode[] };
+}
+
+// ---------- Descriptor + skin contract ----------
+
+export interface InteractionDescriptor<Kind extends string = string> {
+  readonly kind: Kind;
+  readonly schema: ZodType;
+  readonly scoring: "qti-standard";
+  /** The empty/initial response for a fresh attempt at this interaction. */
+  initialResponse(node: InteractionNode): ResponseValue;
+}
+
+export function defineInteraction<Kind extends string>(
+  descriptor: InteractionDescriptor<Kind>,
+): InteractionDescriptor<Kind> {
+  return descriptor;
+}
+
+export type OptionStatus = "idle" | "selected" | "correct" | "incorrect";
+
+/** Whole-interaction status (for interactions without options, e.g. textEntry). */
+export type InteractionStatus = "unanswered" | "answered" | "correct" | "incorrect";
+
+/** Prop-getter result a skin spreads onto an option element to inherit selection + a11y. */
+export interface OptionProps {
+  role: "radio" | "checkbox";
+  tabIndex: number;
+  "aria-checked": boolean;
+  "aria-disabled": boolean;
+  "data-status": OptionStatus;
+  onClick: () => void;
+}
+
+/** Controlled props every interaction skin receives by default (ADR-0002). */
+export interface InteractionRenderProps {
+  node: InteractionNode;
+  responseIdentifier: string;
+  value: ResponseValue;
+  setValue: (value: ResponseValue) => void;
+  /** True after submit — the interaction is read-only. */
+  disabled: boolean;
+  /** True after submit — show correct/incorrect chrome. */
+  showFeedback: boolean;
+  /** Whole-interaction status (drives feedback for option-less interactions). */
+  status: InteractionStatus;
+  getOptionProps: (optionIdentifier: string) => OptionProps;
+  /** Render body fragments (prompt, choice labels) through the core allowlist walk. */
+  renderContent: (nodes: readonly BodyNode[] | undefined) => ReactNode;
+}
+
+export type InteractionSkin = ComponentType<InteractionRenderProps>;
+export type SkinRegistry = Readonly<Record<string, InteractionSkin>>;
+
+export interface QtiRuntimeConfig {
+  readonly interactions: readonly InteractionDescriptor[];
+  readonly skin: SkinRegistry;
+  readonly contentModel?: ContentModel;
+}
+
+export interface ItemRendererProps {
+  item: AssessmentItemView;
+  // Rendered inside the same runtime context as the item body, after it. Lets a consumer
+  // drop controls (a Submit bar, a score panel) that call `useAttempt()` for this item —
+  // the attempt store is per-item and scoped to this subtree.
+  children?: ReactNode;
+}
+
+export interface QtiRuntime {
+  ItemRenderer: ComponentType<ItemRendererProps>;
+  useAttempt: () => AttemptController;
+}
+
+export interface AttemptController extends AttemptSnapshot {
+  submit: () => readonly ScoreResult[];
+  reset: () => void;
+}
+
+// ---------- Internal context ----------
+
+interface RuntimeContextValue {
+  store: AttemptStore;
+  declarationsById: ReadonlyMap<string, ResponseDeclarationView>;
+}
+
+const RuntimeContext = createContext<RuntimeContextValue | null>(null);
+
+function useRuntimeContext(): RuntimeContextValue {
+  const context = useContext(RuntimeContext);
+
+  if (!context) {
+    throw new Error("QTI runtime components must be rendered inside an <ItemRenderer>.");
+  }
+
+  return context;
+}
+
+function responseIncludes(value: ResponseValue, optionIdentifier: string): boolean {
+  if (value === null) {
+    return false;
+  }
+
+  return typeof value === "string" ? value === optionIdentifier : value.includes(optionIdentifier);
+}
+
+function isCorrectOption(declaration: ResponseDeclarationView | undefined, optionIdentifier: string): boolean {
+  return Boolean(declaration?.correctResponse?.values.some((entry) => entry.value === optionIdentifier));
+}
+
+export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
+  const model = config.contentModel ?? v0ContentModel;
+  const descriptorsByKind = new Map(config.interactions.map((descriptor) => [descriptor.kind, descriptor]));
+
+  function renderFlow(node: XmlContentNode, key: number): ReactNode {
+    const isMath = node.name === model.mathRoot;
+
+    if (!isMath && !isAllowedFlowElement(model, node.name)) {
+      return null; // not allowlisted → dropped (the sanitizer)
+    }
+
+    const attributes = sanitizeAttributes(model, node.attributes);
+    const children = node.children?.map((child, index) => renderNode(child, index));
+
+    return createElement(node.name, { key, ...attributes }, node.value ?? children);
+  }
+
+  function renderNode(node: BodyNode, key: number): ReactNode {
+    if (isInteractionKind(model, node.kind) && descriptorsByKind.has(node.kind) && config.skin[node.kind]) {
+      return createElement(InteractionHost, { key, node: node as InteractionNode });
+    }
+
+    if (node.kind === "xml") {
+      return renderFlow(node as XmlContentNode, key);
+    }
+
+    const value = (node as { value?: string }).value;
+
+    return typeof value === "string" ? value : null;
+  }
+
+  function InteractionHost({ node }: { node: InteractionNode }): ReactNode {
+    const { store, declarationsById } = useRuntimeContext();
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+    const responseIdentifier = node.responseIdentifier;
+    const declaration = declarationsById.get(responseIdentifier);
+    const cardinality: Cardinality = declaration?.cardinality ?? "single";
+    const value = snapshot.responses[responseIdentifier] ?? null;
+    const disabled = snapshot.submitted;
+
+    const answered =
+      value !== null &&
+      !(typeof value === "string" && value.trim() === "") &&
+      !(Array.isArray(value) && value.length === 0);
+
+    let status: InteractionStatus = answered ? "answered" : "unanswered";
+
+    if (disabled) {
+      const scored = snapshot.scores.find((score) => score.identifier === responseIdentifier);
+      status = scored?.correct ? "correct" : "incorrect";
+    }
+
+    const setValue = (next: ResponseValue): void => {
+      store.setResponse(responseIdentifier, next);
+    };
+
+    const getOptionProps = (optionIdentifier: string): OptionProps => {
+      const selected = responseIncludes(value, optionIdentifier);
+
+      let status: OptionStatus = selected ? "selected" : "idle";
+
+      if (disabled) {
+        if (isCorrectOption(declaration, optionIdentifier)) {
+          status = "correct";
+        } else if (selected) {
+          status = "incorrect";
+        } else {
+          status = "idle";
+        }
+      }
+
+      return {
+        role: cardinality === "single" ? "radio" : "checkbox",
+        tabIndex: 0,
+        "aria-checked": selected,
+        "aria-disabled": disabled,
+        "data-status": status,
+        onClick: () => {
+          if (disabled) {
+            return;
+          }
+
+          if (cardinality === "single") {
+            setValue(optionIdentifier);
+            return;
+          }
+
+          const current = value === null ? [] : typeof value === "string" ? [value] : [...value];
+          const next = selected
+            ? current.filter((entry) => entry !== optionIdentifier)
+            : [...current, optionIdentifier];
+
+          setValue(next);
+        },
+      };
+    };
+
+    const renderContent = (nodes: readonly BodyNode[] | undefined): ReactNode =>
+      nodes ? nodes.map((child, index) => renderNode(child, index)) : null;
+
+    const Skin = config.skin[node.kind];
+
+    if (!Skin) {
+      return null;
+    }
+
+    return createElement(Skin, {
+      node,
+      responseIdentifier,
+      value,
+      setValue,
+      disabled,
+      showFeedback: disabled,
+      status,
+      getOptionProps,
+      renderContent,
+    });
+  }
+
+  function ItemRenderer({ item, children }: ItemRendererProps): ReactNode {
+    const store = useMemo(() => {
+      const initial: Record<string, ResponseValue> = {};
+
+      for (const node of item.itemBody.content ?? []) {
+        // initial responses are seeded lazily by skins; declarations drive scoring.
+        void node;
+      }
+
+      return createAttemptStore(item.responseDeclarations, initial);
+    }, [item]);
+
+    const declarationsById = useMemo(
+      () => new Map(item.responseDeclarations.map((declaration) => [declaration.identifier, declaration])),
+      [item],
+    );
+
+    const body = (item.itemBody.content ?? []).map((node, index) => renderNode(node, index));
+
+    return createElement(RuntimeContext.Provider, { value: { store, declarationsById } }, body, children);
+  }
+
+  function useAttempt(): AttemptController {
+    const { store } = useRuntimeContext();
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+    return {
+      ...snapshot,
+      submit: store.submit,
+      reset: store.reset,
+    };
+  }
+
+  return { ItemRenderer, useAttempt };
+}

package/src/store.ts

@@ -0,0 +1,92 @@
+/**
+ * The response store the headless core owns (ADR-0002): it holds candidate responses
+ * keyed by `responseIdentifier`, the submitted flag, and the scored outcomes. Skins are
+ * controlled against it; they never own response state (only ephemeral UI state).
+ *
+ * Backed by an external store so `useSyncExternalStore` can subscribe with narrow,
+ * snapshot-stable reads. No React import here — the hook lives in the runtime.
+ */
+
+import { scoreResponse } from "./response-processing";
+import type { ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+
+export interface AttemptSnapshot {
+  readonly responses: Readonly<Record<string, ResponseValue>>;
+  readonly submitted: boolean;
+  readonly scores: readonly ScoreResult[];
+}
+
+export interface AttemptStore {
+  // Function-property signatures (not methods): these are bound arrow functions, safe to
+  // pass by reference (e.g. to useSyncExternalStore).
+  readonly getSnapshot: () => AttemptSnapshot;
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly setResponse: (responseIdentifier: string, value: ResponseValue) => void;
+  readonly submit: () => readonly ScoreResult[];
+  readonly reset: () => void;
+}
+
+export function createAttemptStore(
+  declarations: readonly ResponseDeclarationView[],
+  initialResponses: Readonly<Record<string, ResponseValue>>,
+): AttemptStore {
+  const declarationsById = new Map(declarations.map((declaration) => [declaration.identifier, declaration]));
+  const listeners = new Set<() => void>();
+
+  let snapshot: AttemptSnapshot = {
+    responses: { ...initialResponses },
+    submitted: false,
+    scores: [],
+  };
+
+  function emit(next: AttemptSnapshot): void {
+    snapshot = next;
+
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function computeScores(responses: Readonly<Record<string, ResponseValue>>): readonly ScoreResult[] {
+    return [...declarationsById.values()].map((declaration) =>
+      scoreResponse(declaration, responses[declaration.identifier] ?? null),
+    );
+  }
+
+  // Arrow-function properties: inherently bound, so they can be passed by reference
+  // (e.g. to useSyncExternalStore) without `this` hazards.
+  return {
+    getSnapshot: () => snapshot,
+
+    subscribe: (listener) => {
+      listeners.add(listener);
+
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    setResponse: (responseIdentifier, value) => {
+      if (snapshot.submitted) {
+        return;
+      }
+
+      emit({
+        ...snapshot,
+        responses: { ...snapshot.responses, [responseIdentifier]: value },
+      });
+    },
+
+    submit: () => {
+      const scores = computeScores(snapshot.responses);
+
+      emit({ ...snapshot, submitted: true, scores });
+
+      return scores;
+    },
+
+    reset: () => {
+      emit({ responses: { ...initialResponses }, submitted: false, scores: [] });
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime view types for the headless core. These are structural views of the
+ * `@conform-ed/contracts` QTI 3.0.1 shapes — the runtime validates items with the
+ * contract schemas, but works against these narrowed types because several contract
+ * schemas are `z.lazy` (statically `any`). No React or Mantine here.
+ */
+
+/** A candidate response for one interaction, keyed in state by `responseIdentifier`. */
+export type ResponseValue = string | readonly string[] | null;
+
+export type Cardinality = "single" | "multiple" | "ordered" | "record";
+
+export interface CorrectResponseView {
+  readonly values: ReadonlyArray<{ readonly value: string }>;
+}
+
+export interface MapEntryView {
+  readonly mapKey: string;
+  readonly mappedValue: number;
+  readonly caseSensitive?: boolean;
+}
+
+export interface MappingView {
+  readonly mapEntries: readonly MapEntryView[];
+  readonly lowerBound?: number;
+  readonly upperBound?: number;
+  readonly defaultValue?: number;
+}
+
+export interface ResponseDeclarationView {
+  readonly identifier: string;
+  readonly cardinality: Cardinality;
+  readonly baseType?: string;
+  readonly correctResponse?: CorrectResponseView;
+  readonly mapping?: MappingView;
+}
+
+/** The scored outcome for one response variable. */
+export interface ScoreResult {
+  readonly identifier: string;
+  readonly score: number;
+  readonly maxScore: number;
+  readonly correct: boolean;
+}