@conform-ed/qti-react 0.0.12 → 0.0.14

package/src/pci/markup.ts

@@ -0,0 +1,102 @@
+/**
+ * PCI markup serialization: `qti-interaction-markup` content back to an HTML string
+ * for injection into the host container. PCI markup is module-owned — the module
+ * queries and mutates it directly — so unlike flow content it is not constrained to
+ * the content-model element allowlist. The serializer still strips what must never
+ * reach the DOM statically: event-handler attributes, script-scheme URLs, and
+ * `<script>` elements (modules bring behaviour through the registry, not markup).
+ */
+
+import type { BodyNode, XmlContentNode } from "../runtime";
+
+const voidElements = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "source",
+  "track",
+  "wbr",
+]);
+
+const blockedElements = new Set(["script", "iframe", "object", "embed"]);
+
+const urlAttributes = new Set(["src", "href", "xlink:href", "poster", "data"]);
+
+function escapeText(value: string): string {
+  return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}
+
+function escapeAttribute(value: string): string {
+  return escapeText(value).replace(/"/gu, "&quot;");
+}
+
+function isUnsafeMarkupAttribute(name: string, value: string): boolean {
+  if (/^on/iu.test(name)) {
+    return true;
+  }
+
+  return urlAttributes.has(name.toLowerCase()) && /^\s*(?:javascript|vbscript|data:text\/html)/iu.test(value);
+}
+
+function serializeAttributes(attributes: Record<string, unknown> | undefined): string {
+  if (!attributes) {
+    return "";
+  }
+
+  let result = "";
+
+  for (const [name, raw] of Object.entries(attributes)) {
+    // Attribute values are strings after normalization; anything else is dropped.
+    const value =
+      typeof raw === "string" ? raw : typeof raw === "number" || typeof raw === "boolean" ? String(raw) : undefined;
+
+    if (value !== undefined && !isUnsafeMarkupAttribute(name, value)) {
+      result += ` ${name}="${escapeAttribute(value)}"`;
+    }
+  }
+
+  return result;
+}
+
+function serializeNode(node: BodyNode | string): string {
+  if (typeof node === "string") {
+    return escapeText(node);
+  }
+
+  if (node.kind === "text") {
+    return escapeText((node as { value?: string }).value ?? "");
+  }
+
+  if (node.kind !== "xml") {
+    return ""; // interactions and QTI constructs cannot nest inside PCI markup
+  }
+
+  const xmlNode = node as XmlContentNode;
+  const name = xmlNode.name.toLowerCase();
+
+  if (blockedElements.has(name)) {
+    return "";
+  }
+
+  const attributes = serializeAttributes(xmlNode.attributes);
+
+  if (voidElements.has(name)) {
+    return `<${name}${attributes}>`;
+  }
+
+  const children = (xmlNode.children ?? []).map(serializeNode).join("");
+  const text = xmlNode.value !== undefined ? escapeText(xmlNode.value) : "";
+
+  return `<${name}${attributes}>${text}${children}</${name}>`;
+}
+
+export function serializePciMarkup(nodes: ReadonlyArray<BodyNode | string> | undefined): string {
+  return (nodes ?? []).map(serializeNode).join("");
+}

package/src/pci/mount.ts

@@ -0,0 +1,134 @@
+/**
+ * The PCI mount lifecycle, framework-free (the React skin is a thin wrapper): resolve
+ * the module through the registry (declared interaction modules with primary →
+ * fallback paths, then the bare `module` name), inject the serialized markup, call
+ * `getInstance(dom, configuration, state)`, and hand back a handle the host uses to
+ * collect the response at submit time and to tear the instance down.
+ */
+
+import type { BodyNode } from "../runtime";
+import type { ResponseDeclarationView, ResponseValue } from "../types";
+import { serializePciMarkup } from "./markup";
+import type { PciConfiguration, PciInstance, PciModule, PciModuleRegistry } from "./registry";
+import { pciResponseToValue, valueToPciResponse } from "./response";
+
+/** The adapter's shape for a `portableCustomInteraction` body node. */
+export interface PciInteractionNode {
+  readonly kind: "portableCustomInteraction";
+  readonly responseIdentifier: string;
+  readonly customInteractionTypeIdentifier: string;
+  readonly module?: string;
+  readonly class?: readonly string[];
+  readonly properties?: Readonly<Record<string, string>>;
+  readonly interactionMarkup?: { readonly content?: ReadonlyArray<BodyNode | string> };
+  readonly interactionModules?: {
+    readonly primaryConfiguration?: string;
+    readonly modules?: ReadonlyArray<{
+      readonly id: string;
+      readonly primaryPath?: string;
+      readonly fallbackPath?: string;
+    }>;
+  };
+}
+
+export interface PciMountOptions {
+  readonly container: Element;
+  readonly node: PciInteractionNode;
+  readonly registry: PciModuleRegistry;
+  /** The bound response variable's declaration and current value (for `boundTo`). */
+  readonly declaration?: ResponseDeclarationView;
+  readonly boundValue?: ResponseValue;
+  /** A state string from a previous instance's getState() (session restore). */
+  readonly state?: string;
+  /** PCI `ondone`: the instance finished on its own and reports its response. */
+  readonly ondone?: (value: ResponseValue, state?: string) => void;
+}
+
+export interface PciMountHandle {
+  readonly instance: PciInstance;
+  /** The instance's current response as a runtime ResponseValue. */
+  readonly collectResponse: () => ResponseValue | undefined;
+  readonly getState: () => string | undefined;
+  readonly unmount: () => void;
+}
+
+async function resolveModule(node: PciInteractionNode, registry: PciModuleRegistry): Promise<PciModule> {
+  const preRegistered =
+    registry.resolve(node.customInteractionTypeIdentifier) ??
+    (node.module !== undefined ? registry.resolve(node.module) : undefined);
+
+  if (preRegistered) {
+    return preRegistered;
+  }
+
+  const declared = node.interactionModules?.modules ?? [];
+
+  for (const entry of declared) {
+    const candidates = [entry.primaryPath, entry.fallbackPath].filter(
+      (candidate): candidate is string => candidate !== undefined,
+    );
+
+    await registry.load(entry.id, candidates);
+  }
+
+  if (declared.length === 0 && node.module !== undefined) {
+    await registry.load(node.module, []);
+  }
+
+  const loaded =
+    registry.resolve(node.customInteractionTypeIdentifier) ??
+    (node.module !== undefined ? registry.resolve(node.module) : undefined) ??
+    (declared.length === 1 ? registry.resolve(declared[0]!.id) : undefined);
+
+  if (!loaded) {
+    throw new Error(`No PCI module registered for "${node.customInteractionTypeIdentifier}".`);
+  }
+
+  return loaded;
+}
+
+export async function mountPci(options: PciMountOptions): Promise<PciMountHandle> {
+  const { container, node, registry } = options;
+  const module = await resolveModule(node, registry);
+
+  const markupHost = container.ownerDocument!.createElement("div");
+  markupHost.className = "qti-interaction-markup";
+  markupHost.innerHTML = serializePciMarkup(node.interactionMarkup?.content);
+  container.appendChild(markupHost);
+
+  let resolveReady!: (instance: PciInstance) => void;
+  const ready = new Promise<PciInstance>((resolve) => {
+    resolveReady = resolve;
+  });
+
+  const configuration: PciConfiguration = {
+    properties: node.properties ?? {},
+    responseIdentifier: node.responseIdentifier,
+    ...(options.declaration
+      ? { boundTo: { [node.responseIdentifier]: valueToPciResponse(options.boundValue ?? null, options.declaration) } }
+      : {}),
+    status: "interacting",
+    onready: (instance) => resolveReady(instance),
+    ondone: (_instance, response, state) => options.ondone?.(pciResponseToValue(response), state),
+  };
+
+  // The spec delivers the instance via onready; implementations commonly also return
+  // it from getInstance. Accept either, first one wins.
+  const returned = module.getInstance(container, configuration, options.state);
+
+  if (returned) {
+    resolveReady(returned);
+  }
+
+  const instance = await ready;
+
+  return {
+    instance,
+    collectResponse: () => pciResponseToValue(instance.getResponse()),
+    getState: () => instance.getState?.(),
+    unmount: () => {
+      instance.oncompleted?.();
+      container.replaceChildren();
+    },
+  };
+}

package/src/pci/registry.ts

@@ -0,0 +1,240 @@
+/**
+ * The PCI Module Registry: PCI v1 modules are AMD (`define([deps], factory)`), so the
+ * registry provides a minimal AMD surface — source evaluation with a scoped `define`,
+ * dependency resolution among registered modules, the `qtiCustomInteractionContext`
+ * bridge (`register` keyed by typeIdentifier), and URL loading with primary → fallback
+ * candidates. PCI is a trust boundary: evaluating a module executes item-supplied
+ * code, which is why PCI support is opt-in and never part of `qtiCoreInteractions`.
+ */
+
+/** The configuration handed to `getInstance` (IMS PCI v1). */
+export interface PciConfiguration {
+  readonly properties: Readonly<Record<string, string>>;
+  readonly responseIdentifier?: string;
+  /** The bound response variable's current value in PCI JSON form. */
+  readonly boundTo?: Readonly<Record<string, unknown>>;
+  readonly status?: string;
+  readonly onready?: (instance: PciInstance, state?: string) => void;
+  readonly ondone?: (instance: PciInstance, response: unknown, state?: string, status?: string) => void;
+}
+
+export interface PciInstance {
+  readonly typeIdentifier?: string;
+  getResponse(): unknown;
+  getState?(): string;
+  /** Engine-invoked before the instance is unloaded (cleanup hook). */
+  oncompleted?(): void;
+}
+
+export interface PciModule {
+  readonly typeIdentifier?: string;
+  getInstance(dom: Element, configuration: PciConfiguration, state: string | undefined): PciInstance | undefined;
+}
+
+export interface PciModuleRegistryOptions {
+  /** Base for relative module paths (typically the item package root URL). */
+  readonly baseUrl?: string;
+  /** Module id → path overrides (a parsed `module_resolution.js` paths map). */
+  readonly paths?: Readonly<Record<string, string>>;
+  /** Source fetcher for URL loading; defaults to global fetch. */
+  readonly fetchText?: (url: string) => Promise<string>;
+}
+
+export interface PciModuleRegistry {
+  /** Evaluate AMD source text; its `define` registers under the given module id. */
+  readonly evaluate: (source: string, context: { readonly id: string }) => void;
+  /** Register a prebuilt module directly (bundled PCIs, tests). */
+  readonly registerModule: (id: string, module: PciModule) => void;
+  /** Resolve by module id or by PCI typeIdentifier; undefined when unknown. */
+  readonly resolve: (id: string) => PciModule | undefined;
+  /**
+   * Load a module from candidate paths in order (primary → fallback), falling back to
+   * the registry's `paths` map when no candidates are given.
+   */
+  readonly load: (id: string, candidates: readonly string[]) => Promise<PciModule>;
+}
+
+interface AmdDefinition {
+  readonly dependencies: readonly string[];
+  readonly factory: (...resolved: unknown[]) => unknown;
+}
+
+function defaultFetchText(url: string): Promise<string> {
+  return fetch(url).then((response) => {
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} for ${url}`);
+    }
+
+    return response.text();
+  });
+}
+
+export function createPciModuleRegistry(options: PciModuleRegistryOptions = {}): PciModuleRegistry {
+  const fetchText = options.fetchText ?? defaultFetchText;
+  const definitions = new Map<string, AmdDefinition>();
+  const resolved = new Map<string, unknown>();
+  const byTypeIdentifier = new Map<string, PciModule>();
+
+  /** Modules registered through qtiCustomInteractionContext.register during a resolve. */
+  let contextRegistrations: PciModule[] = [];
+
+  const qtiCustomInteractionContext = {
+    register(module: PciModule): void {
+      contextRegistrations.push(module);
+
+      if (module.typeIdentifier !== undefined) {
+        byTypeIdentifier.set(module.typeIdentifier, module);
+      }
+    },
+  };
+
+  function resolveDependency(id: string, dependedOnBy: string, resolving: Set<string>): unknown {
+    if (id === "qtiCustomInteractionContext") {
+      return qtiCustomInteractionContext;
+    }
+
+    if (resolved.has(id)) {
+      return resolved.get(id);
+    }
+
+    const definition = definitions.get(id);
+
+    if (!definition) {
+      throw new Error(`PCI module "${dependedOnBy}" depends on "${id}", which is not registered.`);
+    }
+
+    return instantiate(id, definition, resolving);
+  }
+
+  function instantiate(id: string, definition: AmdDefinition, resolving: Set<string>): unknown {
+    if (resolving.has(id)) {
+      throw new Error(`Circular PCI module dependency involving "${id}".`);
+    }
+
+    resolving.add(id);
+
+    const dependencies = definition.dependencies.map((dependency) => resolveDependency(dependency, id, resolving));
+    const beforeCount = contextRegistrations.length;
+    const value = definition.factory(...dependencies);
+    // A module that only ctx.register()s (no return value) still resolves to the
+    // registered module — the corpus modules do both.
+    const registered = contextRegistrations.length > beforeCount ? contextRegistrations.at(-1) : undefined;
+    const moduleValue = value ?? registered;
+
+    resolving.delete(id);
+    resolved.set(id, moduleValue);
+
+    const candidate = moduleValue as PciModule | undefined;
+
+    if (candidate?.typeIdentifier !== undefined && typeof candidate.getInstance === "function") {
+      byTypeIdentifier.set(candidate.typeIdentifier, candidate);
+    }
+
+    return moduleValue;
+  }
+
+  function evaluate(source: string, context: { readonly id: string }): void {
+    const define = (...args: unknown[]): void => {
+      // AMD forms: define(factory) | define(deps, factory) | define(id, deps, factory).
+      const id = typeof args[0] === "string" ? (args.shift() as string) : context.id;
+      const dependencies = Array.isArray(args[0]) ? (args.shift() as string[]) : [];
+      const factoryArg = args[0];
+      const factory =
+        typeof factoryArg === "function" ? (factoryArg as AmdDefinition["factory"]) : (): unknown => factoryArg;
+
+      definitions.set(id, { dependencies, factory });
+    };
+
+    (define as { amd?: object }).amd = {};
+
+    // Scoped evaluation: the module sees our `define`, nothing else is injected.
+    // Executing PCI source IS the feature — the documented trust boundary consumers
+    // accept by opting into PCI (this registry is never part of qtiCoreInteractions).
+    // oxlint-disable-next-line typescript/no-implied-eval
+    new Function("define", `"use strict";\n${source}`)(define);
+  }
+
+  function resolve(id: string): PciModule | undefined {
+    const fromType = byTypeIdentifier.get(id);
+
+    if (fromType) {
+      return fromType;
+    }
+
+    if (!resolved.has(id)) {
+      const definition = definitions.get(id);
+
+      if (!definition) {
+        // Possibly a typeIdentifier lookup: typeIdentifiers only become known when a
+        // factory runs (ctx.register), so instantiate pending definitions best-effort
+        // and re-check. Broken pending modules fail on their own by-id resolution.
+        for (const [pendingId, pending] of definitions) {
+          if (!resolved.has(pendingId)) {
+            try {
+              instantiate(pendingId, pending, new Set());
+            } catch {
+              // surfaced when the broken module itself is resolved or loaded
+            }
+          }
+        }
+
+        return byTypeIdentifier.get(id);
+      }
+
+      instantiate(id, definition, new Set());
+    }
+
+    const value = resolved.get(id) as PciModule | undefined;
+
+    return value && typeof value.getInstance === "function" ? value : undefined;
+  }
+
+  function toUrl(path: string): string {
+    const withExtension = /\.[a-z]+$/iu.test(path) ? path : `${path}.js`;
+
+    return options.baseUrl ? new URL(withExtension, options.baseUrl).toString() : withExtension;
+  }
+
+  async function load(id: string, candidates: readonly string[]): Promise<PciModule> {
+    const existing = resolve(id);
+
+    if (existing) {
+      return existing;
+    }
+
+    const pathsEntry = options.paths?.[id];
+    const allCandidates = candidates.length > 0 ? candidates : pathsEntry !== undefined ? [pathsEntry] : [];
+    const failures: string[] = [];
+
+    for (const candidate of allCandidates) {
+      try {
+        evaluate(await fetchText(toUrl(candidate)), { id });
+
+        const module = resolve(id);
+
+        if (module) {
+          return module;
+        }
+
+        failures.push(`${candidate}: evaluated but did not register a PCI module`);
+      } catch (error) {
+        failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    throw new Error(`PCI module "${id}" could not be loaded. ${failures.join("; ") || "No candidate paths."}`);
+  }
+
+  return {
+    evaluate,
+    registerModule: (id, module) => {
+      resolved.set(id, module);
+
+      if (module.typeIdentifier !== undefined) {
+        byTypeIdentifier.set(module.typeIdentifier, module);
+      }
+    },
+    resolve,
+    load,
+  };
+}

package/src/pci/response.ts

@@ -0,0 +1,138 @@
+/**
+ * PCI JSON ↔ ResponseValue conversion (IMS PCI v1 "JSON representation of variable
+ * values"). PCI instances exchange `{ base: { integer: 3 } }` / `{ list: ... }` /
+ * `{ record: [{ name, base }] }` shapes; the attempt store speaks string / string[] /
+ * record-object / null. Record fields keep their runtime type so `fieldValue` in
+ * response processing sees properly typed members.
+ */
+
+import { isResponseRecord } from "../types";
+import type { ResponseDeclarationView, ResponseFieldValue, ResponseValue } from "../types";
+
+function scalarToString(value: unknown): string {
+  if (Array.isArray(value)) {
+    // point / pair / directedPair entries: tuples join with a space, matching the
+    // runtime's response conventions ("x y", "from to").
+    return value.map(String).join(" ");
+  }
+
+  return String(value);
+}
+
+/** First (and per spec only) entry of a base/list payload: `{ integer: 3 }` → 3. */
+function payloadEntry(payload: unknown): unknown {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+
+  const values = Object.values(payload);
+
+  return values.length > 0 ? values[0] : undefined;
+}
+
+/** One `{ name, base }` record entry → a typed field, or null for malformed entries. */
+function recordField(entry: unknown): [string, ResponseFieldValue] | null {
+  if (typeof entry !== "object" || entry === null) {
+    return null;
+  }
+
+  const { name, base } = entry as { name?: unknown; base?: unknown };
+
+  if (typeof name !== "string") {
+    return null;
+  }
+
+  const raw = payloadEntry(base);
+
+  if (raw === undefined || raw === null) {
+    return [name, null];
+  }
+
+  return [name, typeof raw === "boolean" || typeof raw === "number" ? raw : scalarToString(raw)];
+}
+
+export function pciResponseToValue(json: unknown): ResponseValue {
+  if (typeof json !== "object" || json === null) {
+    return null;
+  }
+
+  const shaped = json as { base?: unknown; list?: unknown; record?: unknown };
+
+  if (shaped.base !== undefined) {
+    const entry = payloadEntry(shaped.base);
+
+    return entry === undefined || entry === null ? null : scalarToString(entry);
+  }
+
+  if (shaped.list !== undefined) {
+    const entry = payloadEntry(shaped.list);
+
+    return Array.isArray(entry) ? entry.map(scalarToString) : null;
+  }
+
+  if (Array.isArray(shaped.record)) {
+    return Object.fromEntries(
+      shaped.record.flatMap((entry) => {
+        const field = recordField(entry);
+
+        return field === null ? [] : [field];
+      }),
+    );
+  }
+
+  return null; // unknown shapes
+}
+
+/** PCI JSON base key for a record field, derived from its runtime type. */
+function fieldPciType(value: string | number | boolean): string {
+  return typeof value === "boolean" ? "boolean" : typeof value === "number" ? "float" : "string";
+}
+
+const numericBaseTypes = new Set(["integer", "float"]);
+
+function bindScalar(value: string, baseType: string): unknown {
+  if (numericBaseTypes.has(baseType)) {
+    return Number(value);
+  }
+
+  if (baseType === "boolean") {
+    return value === "true";
+  }
+
+  if (baseType === "point") {
+    return value.split(/\s+/u).map(Number);
+  }
+
+  if (baseType === "pair" || baseType === "directedPair") {
+    return value.split(/\s+/u);
+  }
+
+  return value;
+}
+
+/** The current response in PCI JSON form — fed to `getInstance` as `boundTo`. */
+export function valueToPciResponse(value: ResponseValue, declaration: ResponseDeclarationView): unknown {
+  const baseType = declaration.baseType ?? "string";
+
+  if (value === null || value === undefined) {
+    return { base: null };
+  }
+
+  if (isResponseRecord(value)) {
+    return {
+      record: Object.entries(value).map(([name, member]) =>
+        member === null ? { name, base: null } : { name, base: { [fieldPciType(member)]: member } },
+      ),
+    };
+  }
+
+  if (declaration.cardinality === "single") {
+    const single = Array.isArray(value) ? value[0] : value;
+
+    return single === undefined ? { base: null } : { base: { [baseType]: bindScalar(single, baseType) } };
+  }
+
+  const entries = Array.isArray(value) ? value : [value];
+
+  return { list: { [baseType]: entries.map((entry) => bindScalar(entry, baseType)) } };
+}

package/src/pci/skin.ts

@@ -0,0 +1,86 @@
+/**
+ * The PCI host skin: a thin React wrapper over `mountPci`. It renders the container,
+ * mounts the module instance after first paint, registers a submit-time response
+ * collector with the attempt store, and tears the instance down on unmount. Module
+ * failures render an explicit error note — never a silent drop (ADR-0003).
+ */
+
+import { createElement, useEffect, useRef, useState, type ReactNode } from "react";
+
+import type { InteractionRenderProps, InteractionSkin } from "../runtime";
+import { mountPci, type PciInteractionNode, type PciMountHandle } from "./mount";
+import type { PciModuleRegistry } from "./registry";
+
+export interface PciSkinOptions {
+  readonly registry: PciModuleRegistry;
+}
+
+export function createPciSkin(options: PciSkinOptions): InteractionSkin {
+  return function PciHost(props: InteractionRenderProps): ReactNode {
+    const node = props.node as unknown as PciInteractionNode;
+    const containerRef = useRef<HTMLDivElement | null>(null);
+    const handleRef = useRef<PciMountHandle | null>(null);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+
+    const [mountError, setMountError] = useState<string | null>(null);
+
+    useEffect(() => {
+      const container = containerRef.current;
+
+      if (!container) {
+        return undefined;
+      }
+
+      let cancelled = false;
+      let mounted: PciMountHandle | null = null;
+
+      mountPci({
+        container,
+        node: propsRef.current.node as unknown as PciInteractionNode,
+        registry: options.registry,
+        ondone: (value) => propsRef.current.setValue(value),
+      })
+        .then((handle) => {
+          if (cancelled) {
+            handle.unmount();
+            return;
+          }
+
+          mounted = handle;
+          handleRef.current = handle;
+        })
+        .catch((error: unknown) => {
+          if (!cancelled) {
+            setMountError(error instanceof Error ? error.message : String(error));
+          }
+        });
+
+      return () => {
+        cancelled = true;
+        mounted?.unmount();
+        handleRef.current = null;
+      };
+    }, []);
+
+    // The attempt store pulls the instance's response at submit time.
+    useEffect(() => propsRef.current.registerResponseCollector(() => handleRef.current?.collectResponse()), []);
+
+    return createElement(
+      "div",
+      {
+        "data-qti-interaction": "portableCustomInteraction",
+        "data-qti-pci-type": node.customInteractionTypeIdentifier,
+        className: node.class?.join(" "),
+      },
+      createElement("div", { ref: containerRef, "data-qti-pci-container": "" }),
+      mountError !== null
+        ? createElement(
+            "p",
+            { role: "note", "data-qti-pci-error": "" },
+            `Custom interaction failed to load: ${mountError}`,
+          )
+        : null,
+    );
+  };
+}