@conform-ed/qti-react 0.0.14 → 0.0.16

package/src/runtime.ts

@@ -28,6 +28,8 @@ import {
   v0ContentModel,
   type ContentModel,
 } from "./content-model";
+import { resolveCatalogSupports, type CatalogView, type PnpView, type ResolvedCatalogSupport } from "./pnp";
+import { collectInteractionConstraints } from "./response-validity";
 import { collectRpIssues, collectTemplateIssues } from "./rp";
 import type {
   CustomOperatorImplementation,
@@ -47,6 +49,8 @@ export type { CapabilityIssue, CapabilityIssueType, CapabilityReport } from "./c
 
 export interface XmlContentNode {
   kind: "xml";
+  /** XML namespace URI; foreign vocabularies (SSML) are recognized by it. */
+  namespace?: string;
   name: string;
   value?: string;
   attributes?: Record<string, unknown>;
@@ -69,6 +73,34 @@ export interface FeedbackView {
   content?: readonly BodyNode[];
 }
 
+/** An item's reference to a shared AssessmentStimulus document (§7.6). */
+export interface AssessmentStimulusRefView {
+  readonly identifier: string;
+  readonly href: string;
+  readonly title?: string;
+}
+
+/** Companion materials, structurally as normalized (calculators, rules, protractors, materials). */
+export interface CompanionMaterialsView {
+  readonly calculators?: readonly Record<string, unknown>[];
+  readonly rules?: readonly Record<string, unknown>[];
+  readonly protractors?: readonly Record<string, unknown>[];
+  readonly digitalMaterials?: readonly {
+    readonly fileHref: string;
+    readonly label?: string;
+    readonly mimeType?: string;
+    readonly resourceIcon?: string;
+  }[];
+  readonly physicalMaterials?: readonly string[];
+}
+
+/** The resolved stimulus body, rendered through the same content walk as the item body. */
+export interface StimulusContentView {
+  readonly content: readonly BodyNode[];
+  /** The stimulus document's catalogs (dormant alternative content, §5.29). */
+  readonly catalogs?: readonly CatalogView[];
+}
+
 export interface AssessmentItemView {
   responseDeclarations: readonly ResponseDeclarationView[];
   outcomeDeclarations?: readonly OutcomeDeclarationView[];
@@ -78,6 +110,15 @@ export interface AssessmentItemView {
   /** QTI adaptive item: multiple attempts until completionStatus reaches "completed". */
   adaptive?: boolean;
   modalFeedbacks?: readonly FeedbackView[];
+  assessmentStimulusRefs?: readonly AssessmentStimulusRefView[];
+  /** Every catalog in the item (item-level and nested), pooled for idref resolution. */
+  catalogs?: readonly CatalogView[];
+  /**
+   * Companion materials (§2.13.1): "content props that provide key information to be
+   * used when answering an Item, e.g. a calculator, protractor, lookup chart". The
+   * runtime exposes them; the delivery platform owns the tools themselves.
+   */
+  companionMaterials?: CompanionMaterialsView;
   itemBody: { content?: BodyNode[] };
 }
 
@@ -140,6 +181,12 @@ export interface InteractionRenderProps {
    * interactions like PCI own their response state). Returns the unregister function.
    */
   registerResponseCollector: (collector: () => ResponseValue | undefined) => () => void;
+  /**
+   * Render the active catalog supports for a skin-owned node's data-catalog-idref
+   * (e.g. a choice label) — the same resolution and presentation the core walk
+   * applies to generic flow nodes. Null when nothing is active.
+   */
+  renderCatalogSupports: (catalogIdref: string | undefined) => ReactNode;
 }
 
 /** Per-kind render overrides a skin passes to `renderContent` for nodes it owns. */
@@ -166,6 +213,19 @@ export interface QtiRuntimeConfig {
    * registered classes pass the capability gate; everything else stays unsupported.
    */
   readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+  /**
+   * Resolve an item's shared-stimulus reference to its normalized body content
+   * (synchronous by design, like the session store's resolveItem: load the package's
+   * stimuli before mounting; `stimulusContentFromNormalized` reshapes a normalized
+   * document). Unresolved refs are capability issues, never silent drops (ADR-0003).
+   */
+  readonly resolveStimulus?: (ref: AssessmentStimulusRefView) => StimulusContentView | null;
+  /**
+   * Replaces the default rendering of an active catalog support (the note-role span
+   * appended beside the referenced content). The delivery engine owns presentation —
+   * tooltips, players, glossary panels — the runtime owns resolution.
+   */
+  readonly renderCatalogSupport?: (support: ResolvedCatalogSupport, catalogIdref: string) => ReactNode;
 }
 
 export interface ItemRendererProps {
@@ -178,6 +238,32 @@ export interface ItemRendererProps {
   store?: AttemptStore | undefined;
   /** Clone seed for template processing; store it to replay the same clone. */
   seed?: number | undefined;
+  /**
+   * The item-session state to render. `review` is read-only: "the candidate can
+   * review the qti-item-body along with the responses they gave, but cannot update
+   * or resubmit them". `solution` additionally swaps in the clone's resolved correct
+   * responses ("a way of entering the solution state"); the show-solution gate is
+   * the consumer's (effective ItemSessionControl). Default: "interact".
+   */
+  mode?: ItemRenderMode | undefined;
+  /**
+   * Effective ItemSessionControl show-feedback; consulted only outside `interact`.
+   * `false` withholds modal and integrated feedback — visibility is then
+   * "determined by the default values of the outcome variables" — and is ignored
+   * for adaptive items, per spec.
+   */
+  showFeedback?: boolean | undefined;
+  /**
+   * The candidate's AfA PNP. Activates the item's dormant catalog supports (§5.29):
+   * "A candidate's profile (or assessment program settings) will indicate whether the
+   * candidate should be presented any of the possible supports."
+   */
+  pnp?: PnpView | undefined;
+  /**
+   * Supports in effect beyond the PNP's initial activation — program settings and
+   * candidate-toggled options (activate-as-option-set). Prohibited supports stay out.
+   */
+  activeSupports?: readonly string[] | undefined;
   // 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.
@@ -188,6 +274,10 @@ export interface ContentRendererProps {
   nodes?: readonly BodyNode[] | undefined;
   /** Values for printedVariable (and showHide-gated feedback) inside the content. */
   outcomes?: Readonly<Record<string, OutcomeValue>> | undefined;
+  /** Catalogs referenced by this content (e.g. a test rubric block's catalogInfo). */
+  catalogs?: readonly CatalogView[] | undefined;
+  pnp?: PnpView | undefined;
+  activeSupports?: readonly string[] | undefined;
 }
 
 export interface QtiRuntime {
@@ -198,6 +288,13 @@ export interface QtiRuntime {
    */
   ContentRenderer: ComponentType<ContentRendererProps>;
   useAttempt: () => AttemptController;
+  /**
+   * The active supports resolved for a catalog idref — for skins whose own nodes
+   * carry data-catalog-idref (e.g. a choice label) and consumers building support
+   * UI (glossary panels, toggles). The core walk already decorates generic flow
+   * and block nodes; this is the same resolution by hand.
+   */
+  useCatalogSupports: (catalogIdref: string | undefined) => readonly ResolvedCatalogSupport[];
   /**
    * The Capability Report for an item against this runtime's injected descriptors,
    * skins, and content model. Consumers gate delivery on it (ADR-0003); the
@@ -214,9 +311,21 @@ export interface AttemptController extends AttemptSnapshot {
 
 // ---------- Internal context ----------
 
+/** The item-session states the renderer knows (ItemSessionControl review/solution). */
+export type ItemRenderMode = "interact" | "review" | "solution";
+
 interface RuntimeContextValue {
   store: AttemptStore;
   declarationsById: ReadonlyMap<string, ResponseDeclarationView>;
+  mode: ItemRenderMode;
+  /** show-feedback=false outside interact: modal + integrated feedback withheld. */
+  suppressFeedback: boolean;
+  /** The clone's resolved correct responses — what the solution state displays. */
+  solutionResponses: Readonly<Record<string, ResponseValue>>;
+  /** Declared outcome defaults — feedback visibility "as at the start of each attempt". */
+  defaultOutcomes: Readonly<Record<string, OutcomeValue>>;
+  /** Resolved active catalog supports by catalog id (§5.28 idref resolution). */
+  catalogSupports: ReadonlyMap<string, readonly ResolvedCatalogSupport[]>;
 }
 
 const RuntimeContext = createContext<RuntimeContextValue | null>(null);
@@ -294,6 +403,9 @@ function createStaticStore(outcomes: Readonly<Record<string, OutcomeValue>>): At
     outcomes,
     templateValues: {},
     attemptCount: 1,
+    durationSeconds: null,
+    responseViolations: [],
+    correctResponses: {},
   };
 
   return {
@@ -303,6 +415,8 @@ function createStaticStore(outcomes: Readonly<Record<string, OutcomeValue>>): At
     registerResponseCollector: () => () => {},
     submit: () => [],
     reset: () => {},
+    suspend: () => {},
+    resume: () => {},
   };
 }
 
@@ -322,7 +436,21 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   const descriptorsByKind = new Map(config.interactions.map((descriptor) => [descriptor.kind, descriptor]));
   const resolveAsset = config.assetResolver ?? ((href: string) => href);
 
+  /** SSML 1.1 (§2.13.2): aural annotations whose text renders transparently. */
+  const ssmlNamespace = "http://www.w3.org/2001/10/synthesis";
+
   function renderFlow(node: XmlContentNode, key: number, overrides?: NodeOverrides, inMath = false): ReactNode {
+    // SSML wraps visual text for speech synthesis (alias substitutions, prosody);
+    // rendering the element as HTML would misread it (ssml:sub is not a subscript).
+    // The annotated text passes through; the aural semantics belong to TTS hosts.
+    if (node.namespace === ssmlNamespace) {
+      return createElement(
+        Fragment,
+        { key },
+        node.value ?? node.children?.map((child, index) => renderNode(child, index, overrides, inMath)),
+      );
+    }
+
     const isMath = inMath || node.name === model.mathRoot;
 
     if (!isMath && !isAllowedFlowElement(model, node.name)) {
@@ -361,7 +489,96 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     );
   }
 
-  function renderNode(node: BodyNode, key: number, overrides?: NodeOverrides, inMath = false): ReactNode {
+  /** The catalog reference a node carries: data-catalog-idref on generic xml nodes, the structured field on QTI nodes. */
+  function catalogIdrefOf(node: BodyNode): string | undefined {
+    const value =
+      node.kind === "xml"
+        ? (node as XmlContentNode).attributes?.["data-catalog-idref"]
+        : (node as { dataCatalogIdref?: unknown }).dataCatalogIdref;
+
+    return typeof value === "string" && value !== "" ? value : undefined;
+  }
+
+  /** The default support presentation: a note beside the referenced content. */
+  function renderSupportDefault(
+    support: ResolvedCatalogSupport,
+    catalogIdref: string,
+    key: number,
+    overrides?: NodeOverrides,
+  ): ReactNode {
+    return createElement(
+      "span",
+      {
+        key: `support-${key}`,
+        role: "note",
+        "data-qti-catalog-idref": catalogIdref,
+        "data-qti-support": support.support,
+        ...(support.xmlLang !== undefined ? { lang: support.xmlLang } : {}),
+      },
+      support.content?.map((child, index) => renderNode(child, index, overrides)),
+      // File-backed alternatives default to an accessible link through the Asset
+      // Resolver; players and panels are the delivery engine's (renderCatalogSupport).
+      support.fileHrefs?.map((file, index) =>
+        createElement(
+          "a",
+          { key: `file-${index}`, href: resolveAsset(file.href), type: file.mimeType, "data-qti-support-file": true },
+          support.support,
+        ),
+      ),
+    );
+  }
+
+  /**
+   * Renders a catalog-referencing node: the authored content as-is, then each active
+   * support's resolved alternative content. Dormant content stays dormant — no
+   * resolved supports means the original alone.
+   */
+  function CatalogSupportHost({
+    catalogIdref,
+    node,
+    overrides,
+    inMath,
+  }: {
+    catalogIdref: string;
+    node: BodyNode;
+    overrides?: NodeOverrides | undefined;
+    inMath: boolean;
+  }): ReactNode {
+    const { catalogSupports } = useRuntimeContext();
+    const supports = catalogSupports.get(catalogIdref) ?? [];
+    const original = renderNode(node, 0, overrides, inMath, true);
+
+    if (!supports.length) {
+      return original;
+    }
+
+    return createElement(
+      Fragment,
+      null,
+      original,
+      supports.map((support, index) =>
+        config.renderCatalogSupport
+          ? createElement(Fragment, { key: `support-${index}` }, config.renderCatalogSupport(support, catalogIdref))
+          : renderSupportDefault(support, catalogIdref, index, overrides),
+      ),
+    );
+  }
+
+  function renderNode(
+    node: BodyNode,
+    key: number,
+    overrides?: NodeOverrides,
+    inMath = false,
+    skipCatalog = false,
+  ): ReactNode {
+    if (!skipCatalog) {
+      const catalogIdref = catalogIdrefOf(node);
+
+      if (catalogIdref !== undefined) {
+        return createElement(CatalogSupportHost, { key, catalogIdref, node, overrides, inMath });
+      }
+    }
+
     const override = overrides?.[node.kind];
 
     if (override) {
@@ -439,11 +656,17 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     element: "span" | "div";
     overrides?: NodeOverrides | undefined;
   }): ReactNode {
-    const { store } = useRuntimeContext();
+    const { store, suppressFeedback, defaultOutcomes } = useRuntimeContext();
     const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
-    const outcome = snapshot.outcomes[feedback.outcomeIdentifier] ?? null;
-
-    if (!feedbackVisible(outcome, feedback, snapshot.submitted)) {
+    // Withheld feedback shows "the version of the qti-item-body displayed to the
+    // candidate at the start of each attempt … with the visibility of any integrated
+    // feedback determined by the default values of the outcome variables and not the
+    // values … updated by the invocation of response processing".
+    const outcome = suppressFeedback
+      ? (defaultOutcomes[feedback.outcomeIdentifier] ?? null)
+      : (snapshot.outcomes[feedback.outcomeIdentifier] ?? null);
+
+    if (!feedbackVisible(outcome, feedback, suppressFeedback || snapshot.submitted)) {
       return null;
     }
 
@@ -488,11 +711,14 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   }
 
   function ModalFeedbackHost({ feedback }: { feedback: FeedbackView }): ReactNode {
-    const { store } = useRuntimeContext();
+    const { store, suppressFeedback } = useRuntimeContext();
     const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
     const outcome = snapshot.outcomes[feedback.outcomeIdentifier] ?? null;
 
-    if (!feedbackVisible(outcome, feedback, snapshot.submitted)) {
+    // "If it is 'false' then feedback is not shown. This includes both Modal
+    // Feedback and Integrated Feedback even if the candidate has access to the
+    // review state."
+    if (suppressFeedback || !feedbackVisible(outcome, feedback, snapshot.submitted)) {
       return null;
     }
 
@@ -504,14 +730,24 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
   }
 
   function InteractionHost({ node }: { node: InteractionNode }): ReactNode {
-    const { store, declarationsById } = useRuntimeContext();
+    const { store, declarationsById, mode, suppressFeedback, solutionResponses } = 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;
+    // The solution state displays the clone's correct response in place of the
+    // candidate's ("a way of entering the solution state").
+    const value =
+      mode === "solution"
+        ? (solutionResponses[responseIdentifier] ?? null)
+        : (snapshot.responses[responseIdentifier] ?? null);
+    // Review and solution are read-only: "can review the qti-item-body along with
+    // the responses they gave, but cannot update or resubmit them".
+    const disabled = snapshot.submitted || mode !== "interact";
+    // Correctness chrome is feedback: shown after a submitted attempt unless
+    // show-feedback withholds it — and always in the solution state (its point).
+    const revealed = mode === "solution" || (snapshot.submitted && !suppressFeedback);
 
     const answered =
       value !== null &&
@@ -520,12 +756,16 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
 
     let status: InteractionStatus = answered ? "answered" : "unanswered";
 
-    if (disabled) {
+    if (revealed) {
       const scored = snapshot.scores.find((score) => score.identifier === responseIdentifier);
-      status = scored?.correct ? "correct" : "incorrect";
+      status = mode === "solution" || scored?.correct ? "correct" : "incorrect";
     }
 
     const setValue = (next: ResponseValue): void => {
+      if (disabled) {
+        return;
+      }
+
       store.setResponse(responseIdentifier, next);
     };
 
@@ -534,7 +774,7 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
 
       let status: OptionStatus = selected ? "selected" : "idle";
 
-      if (disabled) {
+      if (revealed) {
         if (isCorrectOption(declaration, optionIdentifier)) {
           status = "correct";
         } else if (selected) {
@@ -574,6 +814,21 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     const renderContent = (nodes: readonly BodyNode[] | undefined, overrides?: NodeOverrides): ReactNode =>
       nodes ? nodes.map((child, index) => renderNode(child, index, overrides)) : null;
 
+    const { catalogSupports } = useRuntimeContext();
+    const renderCatalogSupportsForSkin = (catalogIdref: string | undefined): ReactNode => {
+      const supports = catalogIdref !== undefined ? (catalogSupports.get(catalogIdref) ?? []) : [];
+
+      if (!supports.length) {
+        return null;
+      }
+
+      return supports.map((support, index) =>
+        config.renderCatalogSupport
+          ? createElement(Fragment, { key: `support-${index}` }, config.renderCatalogSupport(support, catalogIdref!))
+          : renderSupportDefault(support, catalogIdref!, index),
+      );
+    };
+
     const Skin = config.skin[node.kind];
 
     if (!Skin) {
@@ -585,8 +840,9 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
       responseIdentifier,
       value,
       setValue,
+      renderCatalogSupports: renderCatalogSupportsForSkin,
       disabled,
-      showFeedback: disabled,
+      showFeedback: revealed,
       status,
       getOptionProps,
       renderContent,
@@ -599,18 +855,41 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     });
   }
 
-  function ContentRenderer({ nodes, outcomes }: ContentRendererProps): ReactNode {
+  function ContentRenderer({ nodes, outcomes, catalogs, pnp, activeSupports }: ContentRendererProps): ReactNode {
     const store = useMemo(() => createStaticStore(outcomes ?? {}), [outcomes]);
     const declarationsById = useMemo(() => new Map<string, ResponseDeclarationView>(), []);
+    const catalogSupports = useMemo(
+      () => resolveCatalogSupports({ catalogs, pnp, activeSupports }).byCatalogId,
+      [catalogs, pnp, activeSupports],
+    );
 
     return createElement(
       RuntimeContext.Provider,
-      { value: { store, declarationsById } },
+      {
+        value: {
+          store,
+          declarationsById,
+          mode: "interact",
+          suppressFeedback: false,
+          solutionResponses: {},
+          defaultOutcomes: {},
+          catalogSupports,
+        },
+      },
       nodes?.map((node, index) => renderNode(node, index)),
     );
   }
 
-  function ItemRenderer({ item, store: externalStore, seed, children }: ItemRendererProps): ReactNode {
+  function ItemRenderer({
+    item,
+    store: externalStore,
+    seed,
+    mode = "interact",
+    showFeedback,
+    pnp,
+    activeSupports,
+    children,
+  }: ItemRendererProps): ReactNode {
     const store = useMemo(
       () =>
         externalStore ??
@@ -626,6 +905,7 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
             seed,
             normalization: config.normalization,
             customOperators: config.customOperators,
+            constraints: collectInteractionConstraints(item.itemBody.content),
           },
         ),
       [item, externalStore, seed],
@@ -636,12 +916,83 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
       [item],
     );
 
+    // "the setting of show-feedback should be ignored for adaptive items when
+    // allow-review is 'true'. When in the review state, the final values of the
+    // outcome variables should be used."
+    const suppressFeedback = mode !== "interact" && showFeedback === false && item.adaptive !== true;
+
+    // Declared outcome defaults, flat-encoded like snapshot outcomes: withheld
+    // feedback re-evaluates against these ("as at the start of each attempt").
+    const defaultOutcomes = useMemo(() => {
+      const defaults: Record<string, OutcomeValue> = {};
+
+      for (const declaration of item.outcomeDeclarations ?? []) {
+        const values = declaration.defaultValue?.values;
+
+        if (values !== undefined) {
+          defaults[declaration.identifier] =
+            declaration.cardinality === "single"
+              ? ((values[0]?.value ?? null) as OutcomeValue)
+              : (values.map((entry) => entry.value) as never);
+        }
+      }
+
+      return defaults;
+    }, [item]);
+
+    // Shared stimulus content renders before the body through the same sanitized
+    // walk; an unresolved ref gets the explicit placeholder (ADR-0003 backstop —
+    // canDeliver already reported it).
+    const stimulusViews = (item.assessmentStimulusRefs ?? []).map((ref) => ({
+      ref,
+      view: config.resolveStimulus?.(ref) ?? null,
+    }));
+
+    // Catalog ids are document-unique; the item's pool and the resolved stimuli's
+    // pool resolve together so idrefs reach across both (§5.28).
+    const catalogSupports = resolveCatalogSupports({
+      catalogs: [...(item.catalogs ?? []), ...stimulusViews.flatMap(({ view }) => view?.catalogs ?? [])],
+      pnp,
+      activeSupports,
+    }).byCatalogId;
+
+    const stimuli = stimulusViews.map(({ ref, view }, index) =>
+      createElement(
+        "section",
+        { key: `stimulus-${index}`, "data-qti-stimulus": ref.identifier },
+        view === null
+          ? createElement(
+              "div",
+              { role: "note", "data-qti-unsupported": "assessmentStimulusRef" },
+              `This content requires a shared stimulus (${ref.href}) this runtime cannot resolve.`,
+            )
+          : view.content.map((node, nodeIndex) => renderNode(node, nodeIndex)),
+      ),
+    );
+
     const body = (item.itemBody.content ?? []).map((node, index) => renderNode(node, index));
     const modals = (item.modalFeedbacks ?? []).map((feedback, index) =>
       createElement(ModalFeedbackHost, { key: index, feedback }),
     );
 
-    return createElement(RuntimeContext.Provider, { value: { store, declarationsById } }, body, modals, children);
+    return createElement(
+      RuntimeContext.Provider,
+      {
+        value: {
+          store,
+          declarationsById,
+          mode,
+          suppressFeedback,
+          solutionResponses: store.getSnapshot().correctResponses,
+          defaultOutcomes,
+          catalogSupports,
+        },
+      },
+      stimuli,
+      body,
+      modals,
+      children,
+    );
   }
 
   function useAttempt(): AttemptController {
@@ -655,6 +1006,14 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     };
   }
 
+  const noSupports: readonly ResolvedCatalogSupport[] = [];
+
+  function useCatalogSupports(catalogIdref: string | undefined): readonly ResolvedCatalogSupport[] {
+    const { catalogSupports } = useRuntimeContext();
+
+    return catalogIdref !== undefined ? (catalogSupports.get(catalogIdref) ?? noSupports) : noSupports;
+  }
+
   function canDeliver(item: AssessmentItemView): CapabilityReport {
     const issues: CapabilityIssue[] = [];
     const seen = new Set<string>();
@@ -740,6 +1099,21 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
       walk(node);
     }
 
+    // Shared stimulus refs must resolve to be deliverable; resolved content passes
+    // through the same content-model gate as the body.
+    for (const ref of item.assessmentStimulusRefs ?? []) {
+      const stimulus = config.resolveStimulus?.(ref) ?? null;
+
+      if (stimulus === null) {
+        report({ type: "unsupported-element", name: "assessmentStimulusRef", detail: ref.href });
+        continue;
+      }
+
+      for (const node of stimulus.content) {
+        walk(node);
+      }
+    }
+
     for (const feedback of item.modalFeedbacks ?? []) {
       for (const child of feedback.content ?? []) {
         walk(child);
@@ -748,7 +1122,10 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
 
     const customOperatorClasses = new Set(Object.keys(config.customOperators ?? {}));
 
-    for (const issue of collectRpIssues(item.responseProcessing, { customOperatorClasses })) {
+    for (const issue of collectRpIssues(item.responseProcessing, {
+      customOperatorClasses,
+      outcomeDeclarations: item.outcomeDeclarations ?? [],
+    })) {
       report(issue);
     }
 
@@ -759,5 +1136,5 @@ export function createQtiRuntime(config: QtiRuntimeConfig): QtiRuntime {
     return { deliverable: issues.length === 0, issues };
   }
 
-  return { ItemRenderer, ContentRenderer, useAttempt, canDeliver };
+  return { ItemRenderer, ContentRenderer, useAttempt, useCatalogSupports, canDeliver };
 }