@conform-ed/qti-react 0.0.12 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conform-ed/qti-react",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "files": [
     "src",
     "dist"
@@ -21,8 +21,10 @@
     "test": "bun test"
   },
   "devDependencies": {
+    "@conform-ed/qti-xml": "0.0.13",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19",
+    "happy-dom": "^20.10.2",
     "react": "^19.2.7",
     "react-dom": "^19"
   },

package/src/capability.ts

@@ -0,0 +1,24 @@
+/**
+ * Capability Report types (ADR-0003): the runtime's answer to "can this content be
+ * delivered, and if not, why". In their own module so the RP interpreter can report
+ * issues without importing the React runtime.
+ */
+
+export type CapabilityIssueType =
+  | "unsupported-interaction"
+  | "invalid-interaction"
+  | "unsupported-element"
+  | "unsupported-rp";
+
+export interface CapabilityIssue {
+  readonly type: CapabilityIssueType;
+  /** The interaction kind, element name, or RP rule/operator/template at issue. */
+  readonly name: string;
+  readonly responseIdentifier?: string;
+  readonly detail?: string;
+}
+
+export interface CapabilityReport {
+  readonly deliverable: boolean;
+  readonly issues: readonly CapabilityIssue[];
+}

package/src/content-model.ts

@@ -13,8 +13,29 @@
  * HTML5 at once".
  */
 
-/** Interaction node kinds the v0 runtime can render. */
-export const v0InteractionKinds = ["choiceInteraction", "textEntryInteraction", "inlineChoiceInteraction"] as const;
+/** Interaction node kinds conform-ed ships descriptors and Reference Skins for. */
+export const v0InteractionKinds = [
+  "associateInteraction",
+  "choiceInteraction",
+  "drawingInteraction",
+  "endAttemptInteraction",
+  "extendedTextInteraction",
+  "gapMatchInteraction",
+  "graphicAssociateInteraction",
+  "graphicGapMatchInteraction",
+  "graphicOrderInteraction",
+  "hotspotInteraction",
+  "hottextInteraction",
+  "inlineChoiceInteraction",
+  "matchInteraction",
+  "mediaInteraction",
+  "orderInteraction",
+  "positionObjectStage",
+  "selectPointInteraction",
+  "sliderInteraction",
+  "textEntryInteraction",
+  "uploadInteraction",
+] as const;
 
 export type V0InteractionKind = (typeof v0InteractionKinds)[number];
 
@@ -26,16 +47,63 @@ const v0FlowElements = new Set<string>([
   "em",
   "b",
   "i",
+  "sub",
+  "sup",
   "br",
   "ul",
   "ol",
   "li",
   // language-critical
   "ruby",
+  "rb",
   "rt",
   "rp",
+  // media (the first media-milestone growth; src/poster route through the Asset Resolver)
+  "img",
+  "audio",
+  "video",
+  "source",
+  "track",
+  "picture",
+  "figure",
+  "figcaption",
+  // embedded media the corpus uses for stages and standalone assets
+  "object",
+  // structural vocabulary the official corpus uses (fixture-driven growth, ADR-0002)
+  "div",
+  "section",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "blockquote",
+  "hr",
+  // tables (gradebook-style content; conservative semantics)
+  "table",
+  "caption",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "th",
+  "td",
 ]);
 
+/** Element-specific attribute allowlists, additive to the global set. */
+const v0ElementAttributes: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ["img", new Set(["src", "alt", "width", "height"])],
+  ["audio", new Set(["src", "controls", "loop", "muted", "preload"])],
+  ["video", new Set(["src", "controls", "loop", "muted", "preload", "poster", "width", "height"])],
+  ["source", new Set(["src", "type"])],
+  ["track", new Set(["src", "kind", "srclang", "label", "default"])],
+  ["object", new Set(["data", "type", "width", "height"])],
+]);
+
+/** Attribute names treated as packaged-asset references (rewritten by the Asset Resolver). */
+const v0UrlAttributes = new Set<string>(["src", "poster", "data"]);
+
 /**
  * The MathML root. Its subtree is rendered structurally (presentation MathML) with the
  * same attribute hardening, but element names inside are not individually allowlisted
@@ -51,6 +119,10 @@ export interface ContentModel {
   readonly flowElements: ReadonlySet<string>;
   readonly mathRoot: string;
   readonly globalAttributes: ReadonlySet<string>;
+  /** Per-element attribute allowlists, additive to `globalAttributes`. */
+  readonly elementAttributes: ReadonlyMap<string, ReadonlySet<string>>;
+  /** Attributes whose values are asset references, routed through the Asset Resolver. */
+  readonly urlAttributes: ReadonlySet<string>;
 }
 
 export const v0ContentModel: ContentModel = {
@@ -58,6 +130,8 @@ export const v0ContentModel: ContentModel = {
   flowElements: v0FlowElements,
   mathRoot: v0MathRoot,
   globalAttributes: v0GlobalAttributes,
+  elementAttributes: v0ElementAttributes,
+  urlAttributes: v0UrlAttributes,
 };
 
 export function isAllowedFlowElement(model: ContentModel, name: string): boolean {
@@ -84,11 +158,13 @@ function isUnsafeAttribute(name: string, value: unknown): boolean {
 }
 
 /**
- * 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.
+ * Reduce a raw attribute bag to the safe, allowlisted subset for one element. Used by
+ * the body walk so a node that validates against QTI structure still cannot carry
+ * script or handlers. The allowlist is the global set plus the element's own entries.
  */
 export function sanitizeAttributes(
   model: ContentModel,
+  elementName: string,
   attributes: Record<string, unknown> | undefined,
 ): Record<string, string> {
   const safe: Record<string, string> = {};
@@ -97,12 +173,14 @@ export function sanitizeAttributes(
     return safe;
   }
 
+  const elementAllowed = model.elementAttributes.get(elementName);
+
   for (const [name, value] of Object.entries(attributes)) {
     if (isUnsafeAttribute(name, value)) {
       continue;
     }
 
-    if (!model.globalAttributes.has(name)) {
+    if (!model.globalAttributes.has(name) && !elementAllowed?.has(name)) {
       continue;
     }
 
@@ -113,3 +191,24 @@ export function sanitizeAttributes(
 
   return safe;
 }
+
+/**
+ * Attribute hardening for MathML subtrees: presentation attributes (mathvariant,
+ * linethickness, …) are not individually allowlisted — MathML has no scripting surface
+ * once event handlers and javascript: URLs are stripped.
+ */
+export function sanitizeMathAttributes(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) && typeof value === "string") {
+      safe[name] = value;
+    }
+  }
+
+  return safe;
+}

package/src/graphic.ts

@@ -0,0 +1,103 @@
+/**
+ * Graphic primitives shared by the graphic interaction family and areaMapping scoring:
+ * QTI shape/coords parsing and point-in-shape hit testing. Pure logic, no React.
+ *
+ * Shapes follow the QTI (HTML image-map) conventions:
+ * - `circle`:  center-x, center-y, radius
+ * - `rect`:    left-x, top-y, right-x, bottom-y
+ * - `poly`:    x1, y1, ..., xn, yn
+ * - `ellipse`: center-x, center-y, radius-x, radius-y
+ * - `default`: the entire image
+ */
+
+export type QtiShape = "circle" | "rect" | "poly" | "ellipse" | "default";
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Parse a QTI coords attribute ("10,20,30") into numbers. */
+export function parseCoords(coords: string): number[] {
+  return coords
+    .split(",")
+    .map((entry) => Number(entry.trim()))
+    .filter((value) => !Number.isNaN(value));
+}
+
+/** Parse a QTI point value ("x y") or null when malformed. */
+export function parsePoint(value: string): Point | null {
+  const [x, y, ...rest] = value.trim().split(/\s+/u).map(Number);
+
+  if (x === undefined || y === undefined || rest.length > 0 || Number.isNaN(x) || Number.isNaN(y)) {
+    return null;
+  }
+
+  return { x, y };
+}
+
+export function formatPoint(point: Point): string {
+  return `${point.x} ${point.y}`;
+}
+
+function pointInPolygon(coords: readonly number[], point: Point): boolean {
+  let inside = false;
+
+  for (let i = 0, j = coords.length - 2; i < coords.length; j = i, i += 2) {
+    const xi = coords[i]!;
+    const yi = coords[i + 1]!;
+    const xj = coords[j]!;
+    const yj = coords[j + 1]!;
+    const intersects = yi > point.y !== yj > point.y && point.x < ((xj - xi) * (point.y - yi)) / (yj - yi) + xi;
+
+    if (intersects) {
+      inside = !inside;
+    }
+  }
+
+  return inside;
+}
+
+/** QTI hit test: is `point` inside the area described by (shape, coords)? */
+export function pointInShape(shape: string, coords: readonly number[], point: Point): boolean {
+  switch (shape) {
+    case "default":
+      return true;
+
+    case "circle": {
+      const [cx, cy, r] = coords;
+
+      if (cx === undefined || cy === undefined || r === undefined) {
+        return false;
+      }
+
+      return (point.x - cx) ** 2 + (point.y - cy) ** 2 <= r ** 2;
+    }
+
+    case "rect": {
+      const [left, top, right, bottom] = coords;
+
+      if (left === undefined || top === undefined || right === undefined || bottom === undefined) {
+        return false;
+      }
+
+      return point.x >= left && point.x <= right && point.y >= top && point.y <= bottom;
+    }
+
+    case "ellipse": {
+      const [cx, cy, rx, ry] = coords;
+
+      if (cx === undefined || cy === undefined || rx === undefined || ry === undefined || rx === 0 || ry === 0) {
+        return false;
+      }
+
+      return (point.x - cx) ** 2 / rx ** 2 + (point.y - cy) ** 2 / ry ** 2 <= 1;
+    }
+
+    case "poly":
+      return coords.length >= 6 && pointInPolygon(coords, point);
+
+    default:
+      return false;
+  }
+}

package/src/index.ts

@@ -12,9 +12,70 @@ export {
   type V0InteractionKind,
 } from "./content-model";
 
-export { foldString, mapResponse, matchCorrect, scoreResponse } from "./response-processing";
+export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
 
-export { createAttemptStore, type AttemptSnapshot, type AttemptStore } from "./store";
+export { assessmentItemViewFromNormalized, assessmentTestViewFromNormalized } from "./normalized-item";
+
+export { formatPoint, parseCoords, parsePoint, pointInShape, type Point, type QtiShape } from "./graphic";
+
+export {
+  applyCorrectResponseOverrides,
+  collectRpIssues,
+  collectTemplateIssues,
+  executeResponseProcessing,
+  executeTemplateProcessing,
+  mulberry32,
+  resolveTemplate,
+} from "./rp";
+
+export type {
+  CustomOperatorImplementation,
+  MaybeRpValue,
+  OutcomeDeclarationView,
+  OutcomeValue,
+  ResponseNormalization,
+  ResponseProcessingContext,
+  ResponseProcessingResult,
+  ResponseProcessingView,
+  RpConditionBranch,
+  RpExpressionView,
+  RpRecordField,
+  RpRuleView,
+  RpScalar,
+  RpValue,
+  TemplateConditionBranch,
+  TemplateDeclarationView,
+  TemplateProcessingContext,
+  TemplateProcessingResult,
+  TemplateProcessingView,
+  TemplateRuleView,
+} from "./rp";
+
+export { createAttemptStore, type AttemptSnapshot, type AttemptStore, type AttemptStoreOptions } from "./store";
+
+export {
+  createTestController,
+  createTestSessionStore,
+  type TestSessionSnapshot,
+  type TestSessionStore,
+  type TestSessionStoreOptions,
+  type AssessmentItemRefView,
+  type AssessmentSectionView,
+  type AssessmentTestView,
+  type BranchRuleView,
+  type ItemSessionControlView,
+  type OutcomeConditionBranch,
+  type OutcomeRuleView,
+  type TestController,
+  type TestFeedbackView,
+  type TestItemResult,
+  type TestPartView,
+  type TestPlan,
+  type TestPlanItem,
+  type TestPlanPart,
+  type TestSessionState,
+  type TimeLimitsView,
+} from "./test";
 
 export {
   createQtiRuntime,
@@ -22,12 +83,18 @@ export {
   type AssessmentItemView,
   type AttemptController,
   type BodyNode,
+  type CapabilityIssue,
+  type CapabilityIssueType,
+  type CapabilityReport,
+  type ContentRendererProps,
+  type FeedbackView,
   type InteractionDescriptor,
   type InteractionNode,
   type InteractionRenderProps,
   type InteractionSkin,
   type InteractionStatus,
   type ItemRendererProps,
+  type NodeOverrides,
   type OptionProps,
   type OptionStatus,
   type QtiRuntime,
@@ -36,9 +103,78 @@ export {
   type XmlContentNode,
 } from "./runtime";
 
-export { choiceInteraction, inlineChoiceInteraction, qtiCoreInteractions, textEntryInteraction } from "./interactions";
+export {
+  createPciModuleRegistry,
+  createPciSkin,
+  mountPci,
+  pciResponseToValue,
+  portableCustomInteraction,
+  serializePciMarkup,
+  valueToPciResponse,
+  type PciConfiguration,
+  type PciInstance,
+  type PciInteractionNode,
+  type PciModule,
+  type PciModuleRegistry,
+  type PciModuleRegistryOptions,
+  type PciMountHandle,
+  type PciMountOptions,
+  type PciSkinOptions,
+} from "./pci";
+
+export {
+  associateInteraction,
+  choiceInteraction,
+  drawingInteraction,
+  endAttemptInteraction,
+  extendedTextInteraction,
+  gapMatchInteraction,
+  graphicAssociateInteraction,
+  graphicGapMatchInteraction,
+  graphicOrderInteraction,
+  hotspotInteraction,
+  hottextInteraction,
+  inlineChoiceInteraction,
+  matchInteraction,
+  mediaInteraction,
+  orderInteraction,
+  positionObjectStage,
+  qtiCoreInteractions,
+  selectPointInteraction,
+  sliderInteraction,
+  textEntryInteraction,
+  uploadInteraction,
+} from "./interactions";
+
+export {
+  AssociateReferenceSkin,
+  ChoiceReferenceSkin,
+  DrawingReferenceSkin,
+  EndAttemptReferenceSkin,
+  ExtendedTextReferenceSkin,
+  GapMatchReferenceSkin,
+  GraphicAssociateReferenceSkin,
+  GraphicGapMatchReferenceSkin,
+  GraphicOrderReferenceSkin,
+  GraphicStage,
+  HotspotReferenceSkin,
+  HottextReferenceSkin,
+  InlineChoiceReferenceSkin,
+  MatchReferenceSkin,
+  MediaReferenceSkin,
+  OrderReferenceSkin,
+  PositionObjectReferenceSkin,
+  SelectPointReferenceSkin,
+  SliderReferenceSkin,
+  TextEntryReferenceSkin,
+  UploadReferenceSkin,
+  referenceSkin,
+  textOf,
+} from "./reference-skin";
 
 export type {
+  AreaMapEntryView,
+  AreaMappingView,
   Cardinality,
   CorrectResponseView,
   MapEntryView,

package/src/interactions/associate.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+const associateInteractionNodeSchema = z.object({
+  kind: z.literal("associateInteraction"),
+  responseIdentifier: z.string().min(1),
+  simpleAssociableChoices: z
+    .array(z.looseObject({ identifier: z.string().min(1), matchMax: z.number().int().optional() }))
+    .min(2),
+  maxAssociations: z.number().int().optional(),
+});
+
+export const associateInteraction = defineInteraction({
+  kind: "associateInteraction",
+  schema: associateInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});

package/src/interactions/drawing.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+const drawingInteractionNodeSchema = z.object({
+  kind: z.literal("drawingInteraction"),
+  responseIdentifier: z.string().min(1),
+  object: z.object({
+    data: z.string().min(1),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    type: z.string().optional(),
+  }),
+});
+
+export const drawingInteraction = defineInteraction({
+  kind: "drawingInteraction",
+  schema: drawingInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});

package/src/interactions/end-attempt.ts

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

package/src/interactions/extended-text.ts

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

package/src/interactions/gap-match.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { defineInteraction } from "../runtime";
+import type { ResponseValue } from "../types";
+
+const gapMatchInteractionNodeSchema = z.object({
+  kind: z.literal("gapMatchInteraction"),
+  responseIdentifier: z.string().min(1),
+  gapTexts: z.array(z.looseObject({ identifier: z.string().min(1), matchMax: z.number().int().optional() })).min(1),
+  // Flow content with `kind: "gap"` nodes nested anywhere inside it. Responses are
+  // directedPairs gapText→gap.
+  content: z.array(z.looseObject({ kind: z.string().min(1) })).min(1),
+});
+
+export const gapMatchInteraction = defineInteraction({
+  kind: "gapMatchInteraction",
+  schema: gapMatchInteractionNodeSchema,
+  scoring: "qti-standard",
+  initialResponse(): ResponseValue {
+    return null;
+  },
+});