@qti-components/portable-custom-interaction 1.1.4 → 1.2.0

package/dist/elements.d.ts

@@ -0,0 +1,10 @@
+import { QtiPortableCustomInteraction } from './qti-portable-custom-interaction';
+import { QtiPortableCustomInteractionTest } from './qti-portable-custom-test-interaction';
+export declare const elements: readonly [{
+    readonly tag: "qti-portable-custom-interaction";
+    readonly ctor: typeof QtiPortableCustomInteraction;
+}, {
+    readonly tag: "qti-portable-custom-interaction-test";
+    readonly ctor: typeof QtiPortableCustomInteractionTest;
+}];
+export { QtiPortableCustomInteraction, QtiPortableCustomInteractionTest };

package/dist/elements.js

@@ -0,0 +1,8 @@
+import { QtiPortableCustomInteraction } from './qti-portable-custom-interaction';
+import { QtiPortableCustomInteractionTest } from './qti-portable-custom-test-interaction';
+export const elements = [
+    { tag: 'qti-portable-custom-interaction', ctor: QtiPortableCustomInteraction },
+    { tag: 'qti-portable-custom-interaction-test', ctor: QtiPortableCustomInteractionTest }
+];
+export { QtiPortableCustomInteraction, QtiPortableCustomInteractionTest };
+//# sourceMappingURL=elements.js.map

package/dist/elements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.js","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,gCAAgC,EAAE,MAAM,wCAAwC,CAAC;AAE1F,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,EAAE,GAAG,EAAE,iCAAiC,EAAE,IAAI,EAAE,4BAA4B,EAAE;IAC9E,EAAE,GAAG,EAAE,sCAAsC,EAAE,IAAI,EAAE,gCAAgC,EAAE;CAC/E,CAAC;AAEX,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,CAAC","sourcesContent":["import { QtiPortableCustomInteraction } from './qti-portable-custom-interaction';\nimport { QtiPortableCustomInteractionTest } from './qti-portable-custom-test-interaction';\n\nexport const elements = [\n  { tag: 'qti-portable-custom-interaction', ctor: QtiPortableCustomInteraction },\n  { tag: 'qti-portable-custom-interaction-test', ctor: QtiPortableCustomInteractionTest }\n] as const;\n\nexport { QtiPortableCustomInteraction, QtiPortableCustomInteractionTest };\n"]}

package/dist/interface.d.ts

@@ -1,9 +1,38 @@
+import type { BaseType, Cardinality } from '@qti-components/base';
 /**
  * Shared status values for PCI lifecycle callbacks.
  *
  * Matches the status vocabulary used in IMS QTI 3 PCI documentation.
  */
 export type PciInteractionStatus = 'interacting' | 'suspended' | 'closed' | 'solution' | 'review';
+/**
+ * Correct response of a response declaration, mirroring `qti-correct-response`.
+ *
+ * `value` holds the authored `qti-value` content: a single value for `single`
+ * cardinality, an array of values for every other cardinality.
+ */
+export interface PciCorrectResponse {
+    value: string | string[];
+}
+/**
+ * Response declaration passed into the `getInstance` configuration so a PCI can
+ * render a correct response itself when the item is in `solution` status.
+ *
+ * Mirrors `qti-response-declaration` with camelCased names. Every field is
+ * optional, a delivery engine passes as much or as little as it has, and
+ * `correctResponse` is absent when the response variable has none.
+ *
+ * `correctResponse` is also withheld while the candidate is still working: it is
+ * only sent when `status` is `solution` or `review`, so a PCI never holds the
+ * answer key during `interacting`.
+ *
+ * See https://github.com/1EdTech/qti-project-management/issues/210
+ */
+export interface PciResponseDeclaration {
+    baseType?: BaseType;
+    cardinality?: Cardinality;
+    correctResponse?: PciCorrectResponse;
+}
 /**
  * Payload passed to `onready` once a PCI reports it is ready.
  */
@@ -34,6 +63,7 @@ export interface ConfigProperties<T> {
     contextVariables: Record<string, unknown>;
     boundTo: unknown;
     responseIdentifier: string;
+    responseDeclaration?: PciResponseDeclaration;
     onready: (payload: PciReadyPayload) => void;
     ondone?: (payload: PciDonePayload) => void;
     status?: PciInteractionStatus;

package/dist/interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"interface.js","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Shared status values for PCI lifecycle callbacks.\n *\n * Matches the status vocabulary used in IMS QTI 3 PCI documentation.\n */\nexport type PciInteractionStatus = 'interacting' | 'suspended' | 'closed' | 'solution' | 'review';\n\n/**\n * Payload passed to `onready` once a PCI reports it is ready.\n */\nexport interface PciReadyPayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // Current status\n}\n\n/**\n * Payload that may be passed to `ondone` when PCI finishes candidate interaction.\n */\nexport interface PciDonePayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // The final status after completion\n  outcome?: unknown; // Optional outcome data (e.g., score, correctness)\n}\n\n/**\n * Configuration object shape exposed to a PCI instance.\n *\n * Notes for authors:\n * - `properties` contains `data-*` attributes from the host element using dataset rules.\n * - `templateVariables`, `contextVariables`, and `boundTo` follow QTI Appendix-C style JSON values.\n * - `onready` must be called by the PCI once it is interactive.\n * - `ondone` is optional and may be used for explicit completion workflows.\n */\nexport interface ConfigProperties<T> {\n  properties: T; // Follows dataset conversion rules (camelCased keys)\n  templateVariables: Record<string, unknown>; // Follows structure in Appendix C\n  contextVariables: Record<string, unknown>; // Follows structure in Appendix C\n  boundTo: unknown; // Follows structure in Appendix C\n  responseIdentifier: string; // Unique within interaction scope\n\n  onready: (payload: PciReadyPayload) => void; // Callback for when PCI is fully constructed and ready\n  ondone?: (payload: PciDonePayload) => void; // Optional callback when candidate finishes interaction\n\n  status?: PciInteractionStatus; // Optional, defaults to \"interacting\"\n}\n\n/**\n * IMS-style PCI factory and instance contract.\n *\n * A PCI module registers an object with a `typeIdentifier` and a `getInstance(...)` factory method.\n * The returned PCI instance should implement response/state read/write methods.\n */\nexport interface IMSpci<T> {\n  /**\n   * Stable PCI type key, expected to match `custom-interaction-type-identifier`.\n   */\n  typeIdentifier: string;\n\n  /** @access public\n   *  @method getInstance Create a new instance of this portable custom interaction\n   *  Will be called by the qtiCustomInteractionContext\n   *  @param {DOM Element} dom - the DOM Element this PCI is being added to\n   *  @param {Object} configuration - the configuration to apply to this PCI\n   *  @param {String} state - a previous saved state to apply to this instance.\n   *  This must have been obtained from a prior call to getState on an\n   *  instance of this type (same typeIdentifier)\n   */\n  getInstance: (dom: HTMLElement, configuration: Configuration<T>, state: string) => void;\n\n  /** @access public\n   * @method getResponse\n   * @return {Object} - the value to assign to the bound QTI response variable\n   */\n  getResponse: () => QtiVariableJSON | undefined;\n\n  /** @access public\n   * @method setResponse\n   * @param {Object} value - the value to assign to the bound QTI response variable\n   * NOTE: This is not an official QTI method, so no guarantee it is implemented\n   * in all PCIs.\n   */\n  setResponse: (value: QtiVariableJSON) => void;\n\n  /** @access public\n   * @method getState\n   * @return {String} The current state of this PCI. May be passed to\n   * getInstance to later restore this PCI instance.\n   * FIXME: host runtime can round-trip object states via prefixed JSON strings;\n   * this type remains `string` for IMS compatibility.\n   */\n  getState: () => string;\n\n  /** @access public\n   * @method setState\n   * @param {String} value - a state previously obtained from getState\n   * to restore this PCI instance to a prior state.\n   * FIXME: runtime may deserialize prefixed JSON state before applying it.\n   */\n  setState(value: string): unknown;\n\n  /**\n   * Optional teardown callback. If present, host may call before unload/cleanup.\n   */\n  oncompleted?: () => void;\n\n  /**\n   * Non-standard optional destroy hook; included for compatibility with legacy engines.\n   */\n  destroy?: () => void; // Not used in IMS and not in TAO implementation, so not used here (optional)\n}\n\n/**\n * Bridge callback signature used by this codebase for PCI registration.\n *\n * IMPORTANT:\n * - This type is intentionally minimal for existing call sites.\n * - Runtime initialization payload in `qti-portable-custom-interaction.ts` contains\n *   additional fields (`boundTo`, `templateVariables`, `contextVariables`, etc.).\n * FIXME: align this type with runtime payload to remove ambiguity in generated docs.\n */\nexport declare type Configuration<T> = {\n  onready: (pci: IMSpci<ConfigProperties<T>>, state?: string) => void;\n  properties: T;\n  // PK: following this: https://www.imsglobal.org/spec/qti/v3p0/impl#h.1mc9puik2ft6\n  // All below are not used in the IMS Reference implementation, keeping for ref\n  /*    \n  ondone: (pci: IMSPci<T>,response:any,state:string, status?: \"interacting\" | \"closed\" | \"solution\" | \"review\" ) => void;\n  status: string;\n  templateVariables: any;  \n  boundTo: any;\n  contextVariables\n  responseIdentifier\n  */\n};\n\n/**\n * QTI base-type `file` representation.\n */\nexport type QtiFileData = {\n  data: string;\n  mime: string;\n  name?: string;\n};\n\nexport type QtiBaseBoolean = boolean;\nexport type QtiBaseInteger = number;\nexport type QtiBaseFloat = number;\nexport type QtiBaseString = string;\nexport type QtiBasePoint = [number, number];\nexport type QtiBasePair = [string, string];\nexport type QtiBaseDirectedPair = [string, string];\nexport type QtiBaseDuration = string; // ISO 8601 duration format\nexport type QtiBaseFile = QtiFileData;\nexport type QtiBaseUri = string;\nexport type QtiBaseIntOrIdentifier = number | string;\nexport type QtiBaseIdentifier = string;\n\n/**\n * Convenience union for primitive response values used by this implementation.\n */\nexport type ResponseType =\n  | boolean\n  | number\n  | string\n  | QtiBasePair\n  | QtiBasePoint\n  | QtiFileData\n  | Array<boolean | number | string | QtiBasePair | QtiBasePoint | QtiFileData>;\n\n/**\n * A QTI record entry for `record` cardinality values.\n */\nexport type QtiRecordItem = {\n  name: string;\n  base?: QtiBaseTypeJSON | null;\n  list?: QtiListTypeJSON | null;\n};\nexport type ResponseVariableType = QtiVariableJSON;\n\n/**\n * QTI Appendix-C style JSON representation for base cardinality.\n */\nexport type QtiBaseTypeJSON = {\n  boolean?: QtiBaseBoolean;\n  integer?: QtiBaseInteger;\n  float?: QtiBaseFloat;\n  string?: QtiBaseString;\n  point?: QtiBasePoint;\n  pair?: QtiBasePair;\n  directedPair?: QtiBaseDirectedPair;\n  duration?: QtiBaseDuration;\n  file?: QtiBaseFile;\n  uri?: QtiBaseUri;\n  intOrIdentifier?: QtiBaseIntOrIdentifier;\n  identifier?: QtiBaseIdentifier;\n} | null;\n\n/**\n * QTI Appendix-C style JSON representation for list cardinality.\n */\nexport type QtiListTypeJSON = {\n  boolean?: QtiBaseBoolean[];\n  integer?: QtiBaseInteger[];\n  float?: QtiBaseFloat[];\n  string?: QtiBaseString[];\n  point?: QtiBasePoint[];\n  pair?: QtiBasePair[];\n  directedPair?: QtiBaseDirectedPair[];\n  duration?: QtiBaseDuration[];\n  file?: QtiBaseFile[];\n  uri?: QtiBaseUri[];\n  intOrIdentifier?: QtiBaseIntOrIdentifier[];\n  identifier?: QtiBaseIdentifier[];\n} | null;\n\n/**\n * Complete QTI variable JSON envelope used by PCI bridge messaging.\n */\nexport declare type QtiVariableJSON = {\n  base?: QtiBaseTypeJSON;\n  list?: QtiListTypeJSON;\n  record?: QtiRecordItem[] | null;\n};\n\n/**\n * RequireJS module resolution config accepted by helper utilities and stories.\n */\nexport interface ModuleResolutionConfig {\n  waitSeconds?: number;\n  context?: string;\n  catchError?: boolean;\n  paths: {\n    [key: string]: string | string[];\n  };\n  shim?: {\n    [key: string]: {\n      deps?: string[]; // Array of dependencies\n      exports?: string; // The global variable to use as the module's value\n    };\n  };\n}\n"]}
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"","sourcesContent":["import type { BaseType, Cardinality } from '@qti-components/base';\n\n/**\n * Shared status values for PCI lifecycle callbacks.\n *\n * Matches the status vocabulary used in IMS QTI 3 PCI documentation.\n */\nexport type PciInteractionStatus = 'interacting' | 'suspended' | 'closed' | 'solution' | 'review';\n\n/**\n * Correct response of a response declaration, mirroring `qti-correct-response`.\n *\n * `value` holds the authored `qti-value` content: a single value for `single`\n * cardinality, an array of values for every other cardinality.\n */\nexport interface PciCorrectResponse {\n  value: string | string[];\n}\n\n/**\n * Response declaration passed into the `getInstance` configuration so a PCI can\n * render a correct response itself when the item is in `solution` status.\n *\n * Mirrors `qti-response-declaration` with camelCased names. Every field is\n * optional, a delivery engine passes as much or as little as it has, and\n * `correctResponse` is absent when the response variable has none.\n *\n * `correctResponse` is also withheld while the candidate is still working: it is\n * only sent when `status` is `solution` or `review`, so a PCI never holds the\n * answer key during `interacting`.\n *\n * See https://github.com/1EdTech/qti-project-management/issues/210\n */\nexport interface PciResponseDeclaration {\n  baseType?: BaseType;\n  cardinality?: Cardinality;\n  correctResponse?: PciCorrectResponse;\n}\n\n/**\n * Payload passed to `onready` once a PCI reports it is ready.\n */\nexport interface PciReadyPayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // Current status\n}\n\n/**\n * Payload that may be passed to `ondone` when PCI finishes candidate interaction.\n */\nexport interface PciDonePayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // The final status after completion\n  outcome?: unknown; // Optional outcome data (e.g., score, correctness)\n}\n\n/**\n * Configuration object shape exposed to a PCI instance.\n *\n * Notes for authors:\n * - `properties` contains `data-*` attributes from the host element using dataset rules.\n * - `templateVariables`, `contextVariables`, and `boundTo` follow QTI Appendix-C style JSON values.\n * - `onready` must be called by the PCI once it is interactive.\n * - `ondone` is optional and may be used for explicit completion workflows.\n */\nexport interface ConfigProperties<T> {\n  properties: T; // Follows dataset conversion rules (camelCased keys)\n  templateVariables: Record<string, unknown>; // Follows structure in Appendix C\n  contextVariables: Record<string, unknown>; // Follows structure in Appendix C\n  boundTo: unknown; // Follows structure in Appendix C\n  responseIdentifier: string; // Unique within interaction scope\n  responseDeclaration?: PciResponseDeclaration; // Optional; carries correctResponse only when status is solution/review\n\n  onready: (payload: PciReadyPayload) => void; // Callback for when PCI is fully constructed and ready\n  ondone?: (payload: PciDonePayload) => void; // Optional callback when candidate finishes interaction\n\n  status?: PciInteractionStatus; // Optional, defaults to \"interacting\"\n}\n\n/**\n * IMS-style PCI factory and instance contract.\n *\n * A PCI module registers an object with a `typeIdentifier` and a `getInstance(...)` factory method.\n * The returned PCI instance should implement response/state read/write methods.\n */\nexport interface IMSpci<T> {\n  /**\n   * Stable PCI type key, expected to match `custom-interaction-type-identifier`.\n   */\n  typeIdentifier: string;\n\n  /** @access public\n   *  @method getInstance Create a new instance of this portable custom interaction\n   *  Will be called by the qtiCustomInteractionContext\n   *  @param {DOM Element} dom - the DOM Element this PCI is being added to\n   *  @param {Object} configuration - the configuration to apply to this PCI\n   *  @param {String} state - a previous saved state to apply to this instance.\n   *  This must have been obtained from a prior call to getState on an\n   *  instance of this type (same typeIdentifier)\n   */\n  getInstance: (dom: HTMLElement, configuration: Configuration<T>, state: string) => void;\n\n  /** @access public\n   * @method getResponse\n   * @return {Object} - the value to assign to the bound QTI response variable\n   */\n  getResponse: () => QtiVariableJSON | undefined;\n\n  /** @access public\n   * @method setResponse\n   * @param {Object} value - the value to assign to the bound QTI response variable\n   * NOTE: This is not an official QTI method, so no guarantee it is implemented\n   * in all PCIs.\n   */\n  setResponse: (value: QtiVariableJSON) => void;\n\n  /** @access public\n   * @method getState\n   * @return {String} The current state of this PCI. May be passed to\n   * getInstance to later restore this PCI instance.\n   * FIXME: host runtime can round-trip object states via prefixed JSON strings;\n   * this type remains `string` for IMS compatibility.\n   */\n  getState: () => string;\n\n  /** @access public\n   * @method setState\n   * @param {String} value - a state previously obtained from getState\n   * to restore this PCI instance to a prior state.\n   * FIXME: runtime may deserialize prefixed JSON state before applying it.\n   */\n  setState(value: string): unknown;\n\n  /**\n   * Optional teardown callback. If present, host may call before unload/cleanup.\n   */\n  oncompleted?: () => void;\n\n  /**\n   * Non-standard optional destroy hook; included for compatibility with legacy engines.\n   */\n  destroy?: () => void; // Not used in IMS and not in TAO implementation, so not used here (optional)\n}\n\n/**\n * Bridge callback signature used by this codebase for PCI registration.\n *\n * IMPORTANT:\n * - This type is intentionally minimal for existing call sites.\n * - Runtime initialization payload in `qti-portable-custom-interaction.ts` contains\n *   additional fields (`boundTo`, `templateVariables`, `contextVariables`, etc.).\n * FIXME: align this type with runtime payload to remove ambiguity in generated docs.\n */\nexport declare type Configuration<T> = {\n  onready: (pci: IMSpci<ConfigProperties<T>>, state?: string) => void;\n  properties: T;\n  // PK: following this: https://www.imsglobal.org/spec/qti/v3p0/impl#h.1mc9puik2ft6\n  // All below are not used in the IMS Reference implementation, keeping for ref\n  /*    \n  ondone: (pci: IMSPci<T>,response:any,state:string, status?: \"interacting\" | \"closed\" | \"solution\" | \"review\" ) => void;\n  status: string;\n  templateVariables: any;  \n  boundTo: any;\n  contextVariables\n  responseIdentifier\n  */\n};\n\n/**\n * QTI base-type `file` representation.\n */\nexport type QtiFileData = {\n  data: string;\n  mime: string;\n  name?: string;\n};\n\nexport type QtiBaseBoolean = boolean;\nexport type QtiBaseInteger = number;\nexport type QtiBaseFloat = number;\nexport type QtiBaseString = string;\nexport type QtiBasePoint = [number, number];\nexport type QtiBasePair = [string, string];\nexport type QtiBaseDirectedPair = [string, string];\nexport type QtiBaseDuration = string; // ISO 8601 duration format\nexport type QtiBaseFile = QtiFileData;\nexport type QtiBaseUri = string;\nexport type QtiBaseIntOrIdentifier = number | string;\nexport type QtiBaseIdentifier = string;\n\n/**\n * Convenience union for primitive response values used by this implementation.\n */\nexport type ResponseType =\n  | boolean\n  | number\n  | string\n  | QtiBasePair\n  | QtiBasePoint\n  | QtiFileData\n  | Array<boolean | number | string | QtiBasePair | QtiBasePoint | QtiFileData>;\n\n/**\n * A QTI record entry for `record` cardinality values.\n */\nexport type QtiRecordItem = {\n  name: string;\n  base?: QtiBaseTypeJSON | null;\n  list?: QtiListTypeJSON | null;\n};\nexport type ResponseVariableType = QtiVariableJSON;\n\n/**\n * QTI Appendix-C style JSON representation for base cardinality.\n */\nexport type QtiBaseTypeJSON = {\n  boolean?: QtiBaseBoolean;\n  integer?: QtiBaseInteger;\n  float?: QtiBaseFloat;\n  string?: QtiBaseString;\n  point?: QtiBasePoint;\n  pair?: QtiBasePair;\n  directedPair?: QtiBaseDirectedPair;\n  duration?: QtiBaseDuration;\n  file?: QtiBaseFile;\n  uri?: QtiBaseUri;\n  intOrIdentifier?: QtiBaseIntOrIdentifier;\n  identifier?: QtiBaseIdentifier;\n} | null;\n\n/**\n * QTI Appendix-C style JSON representation for list cardinality.\n */\nexport type QtiListTypeJSON = {\n  boolean?: QtiBaseBoolean[];\n  integer?: QtiBaseInteger[];\n  float?: QtiBaseFloat[];\n  string?: QtiBaseString[];\n  point?: QtiBasePoint[];\n  pair?: QtiBasePair[];\n  directedPair?: QtiBaseDirectedPair[];\n  duration?: QtiBaseDuration[];\n  file?: QtiBaseFile[];\n  uri?: QtiBaseUri[];\n  intOrIdentifier?: QtiBaseIntOrIdentifier[];\n  identifier?: QtiBaseIdentifier[];\n} | null;\n\n/**\n * Complete QTI variable JSON envelope used by PCI bridge messaging.\n */\nexport declare type QtiVariableJSON = {\n  base?: QtiBaseTypeJSON;\n  list?: QtiListTypeJSON;\n  record?: QtiRecordItem[] | null;\n};\n\n/**\n * RequireJS module resolution config accepted by helper utilities and stories.\n */\nexport interface ModuleResolutionConfig {\n  waitSeconds?: number;\n  context?: string;\n  catchError?: boolean;\n  paths: {\n    [key: string]: string | string[];\n  };\n  shim?: {\n    [key: string]: {\n      deps?: string[]; // Array of dependencies\n      exports?: string; // The global variable to use as the module's value\n    };\n  };\n}\n"]}

package/dist/qti-portable-custom-interaction.d.ts

@@ -1,17 +1,17 @@
 import { Interaction } from '@qti-components/base';
 import type { CSSResultGroup } from 'lit';
 import type { BaseType, Cardinality, ItemContext, QtiContext } from '@qti-components/base';
-import type { QtiVariableJSON, ResponseVariableType } from './interface';
+import type { PciInteractionStatus, PciResponseDeclaration, QtiVariableJSON, ResponseVariableType } from './interface';
 export declare class QtiPortableCustomInteraction extends Interaction {
     #private;
     protected _iframeLoaded: boolean;
+    protected _interactionReady: boolean;
     protected _pendingMessages: Array<{
         method: string;
         params: any;
     }>;
     protected iframe: HTMLIFrameElement;
     protected _iframeMessageOrigin: string | null;
-    private _iframeObjectUrl;
     static styles: CSSResultGroup;
     module: string;
     customInteractionTypeIdentifier: string;
@@ -20,6 +20,22 @@ export declare class QtiPortableCustomInteraction extends Interaction {
     requireJsUrl: string;
     baseUrl: string;
     useDefaultPaths: boolean;
+    /**
+     * Item lifecycle status handed to the PCI in its `getInstance` configuration.
+     * A delivery engine sets `solution` to let a PCI render the correct response.
+     */
+    status: PciInteractionStatus;
+    /**
+     * Response declaration passed into the PCI configuration, so a PCI can render
+     * the correct response itself instead of having it pushed in as a response.
+     *
+     * Derived from the item context, unless a host sets it explicitly - the
+     * correct response viewer does, since it has no response declaration of its own.
+     *
+     * See https://github.com/1EdTech/qti-project-management/issues/210
+     */
+    set responseDeclaration(declaration: PciResponseDeclaration | null);
+    get responseDeclaration(): PciResponseDeclaration | null;
     private _errorMessage;
     protected context?: ItemContext;
     protected qtiContext?: QtiContext;
@@ -91,12 +107,6 @@ export declare class QtiPortableCustomInteraction extends Interaction {
      * IFRAME MODE: Generate iframe HTML content
      */
     protected generateIframeContent(): string;
-    /**
-     * Toggle the display of the correct response
-     * @param responseVariable The response variable containing the correct response
-     * @param show Whether to show or hide the correct response
-     */
-    toggleInternalCorrectResponse(show: boolean): void;
     /**
      * Method to disable the PCI for review mode
      * This can be used when showing the correct response

package/dist/qti-portable-custom-interaction.js

@@ -7,20 +7,39 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { css, html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { consume } from '@lit/context';
-import { Interaction, itemContext, qtiContext, removeDoubleSlashes } from '@qti-components/base';
+import { Interaction, itemContext, qtiContext, removeDoubleSlashes, responseAttributeConverter } from '@qti-components/base';
 import styles from './qti-portable-custom-interaction.styles';
+/** Statuses in which the item is showing the correct response, so a PCI may legitimately see it. */
+const STATUSES_SHOWING_CORRECT_RESPONSE = ['solution', 'review'];
+/**
+ * Whether a response variable actually declares a correct response.
+ *
+ * Non-single cardinality yields `[]` for an empty `<qti-correct-response>`, which is "no correct
+ * response" and must not be reported as one.
+ */
+function hasCorrectResponseValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    return Array.isArray(value) ? value.length > 0 : value !== '';
+}
 export class QtiPortableCustomInteraction extends Interaction {
     constructor() {
         super(...arguments);
         this._iframeLoaded = false;
+        this._interactionReady = false;
         this._pendingMessages = [];
         this._iframeMessageOrigin = null;
-        this._iframeObjectUrl = null;
         this.requirePathsJson = '';
         this.requireShimJson = '';
         this.requireJsUrl = 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js';
         this.baseUrl = '';
         this.useDefaultPaths = false;
+        /**
+         * Item lifecycle status handed to the PCI in its `getInstance` configuration.
+         * A delivery engine sets `solution` to let a PCI render the correct response.
+         */
+        this.status = 'interacting';
+        this.#responseDeclaration = null;
         this._errorMessage = null;
         this.response = null;
         this.#parsedRequirePaths = null;
@@ -50,6 +69,7 @@ export class QtiPortableCustomInteraction extends Interaction {
             }
             switch (data.method) {
                 case 'iframeReady':
+                    this._interactionReady = true;
                     this.#initializeInteraction();
                     this.#processPendingMessages();
                     this.dispatchEvent(new CustomEvent('qti-portable-custom-interaction-loaded', {
@@ -144,6 +164,59 @@ export class QtiPortableCustomInteraction extends Interaction {
       }
     `
     ]; }
+    #responseDeclaration;
+    /**
+     * Response declaration passed into the PCI configuration, so a PCI can render
+     * the correct response itself instead of having it pushed in as a response.
+     *
+     * Derived from the item context, unless a host sets it explicitly - the
+     * correct response viewer does, since it has no response declaration of its own.
+     *
+     * See https://github.com/1EdTech/qti-project-management/issues/210
+     */
+    set responseDeclaration(declaration) {
+        this.#responseDeclaration = declaration;
+    }
+    get responseDeclaration() {
+        if (this.#responseDeclaration) {
+            return this.#responseDeclaration;
+        }
+        const variable = this.responseVariable;
+        if (!variable) {
+            return null;
+        }
+        const declaration = {
+            baseType: variable.baseType,
+            cardinality: variable.cardinality
+        };
+        const correctResponse = variable.correctResponse;
+        if (hasCorrectResponseValue(correctResponse)) {
+            declaration.correctResponse = { value: correctResponse };
+        }
+        return declaration;
+    }
+    /**
+     * The declaration as it goes into the PCI configuration.
+     *
+     * `correctResponse` is withheld unless the item is actually showing a solution. A PCI is
+     * third-party code running in an iframe, and there is no reason for it to hold the answer key
+     * while the candidate is still working - the use case this field exists for only applies once
+     * the status says the correct response is being shown.
+     *
+     * The filter sits here rather than in the `responseDeclaration` getter so it also covers a
+     * declaration a host set explicitly, not just the one derived from the item context.
+     */
+    #responseDeclarationForStatus() {
+        const declaration = this.responseDeclaration;
+        if (!declaration?.correctResponse) {
+            return declaration;
+        }
+        if (STATUSES_SHOWING_CORRECT_RESPONSE.includes(this.status)) {
+            return declaration;
+        }
+        const { correctResponse: _withheld, ...rest } = declaration;
+        return rest;
+    }
     #parsedRequirePaths;
     #parsedRequireShim;
     #pciValidity;
@@ -575,10 +648,6 @@ export class QtiPortableCustomInteraction extends Interaction {
     disconnectedCallback() {
         super.disconnectedCallback();
         window.removeEventListener('message', this.handleIframeMessage);
-        if (this._iframeObjectUrl) {
-            URL.revokeObjectURL(this._iframeObjectUrl);
-            this._iframeObjectUrl = null;
-        }
     }
     /**
      * IFRAME MODE: Send message to iframe
@@ -611,10 +680,7 @@ export class QtiPortableCustomInteraction extends Interaction {
      * IFRAME MODE: Create iframe element
      */
     createIframe() {
-        if (this._iframeObjectUrl) {
-            URL.revokeObjectURL(this._iframeObjectUrl);
-            this._iframeObjectUrl = null;
-        }
+        this._interactionReady = false;
         this.iframe = document.createElement('iframe');
         this.iframe.id = `pci-iframe-${this.responseIdentifier}`;
         this.iframe.setAttribute('title', 'QTI PCI Iframe');
@@ -627,10 +693,6 @@ export class QtiPortableCustomInteraction extends Interaction {
         // Handle iframe load event
         this.iframe.onload = () => {
             this._iframeLoaded = true;
-            if (this._iframeObjectUrl) {
-                URL.revokeObjectURL(this._iframeObjectUrl);
-                this._iframeObjectUrl = null;
-            }
             this.#addMarkupToIframe();
             // Send initialization data to iframe
             this.#sendIframeInitData();
@@ -640,16 +702,14 @@ export class QtiPortableCustomInteraction extends Interaction {
         this.iframe.name = iframeName;
         // Generate iframe HTML content with all required scripts
         const iframeContent = this.generateIframeContent();
-        // Prefer a same-origin blob URL to avoid postMessage target-origin mismatches (e.g. in Storybook).
-        try {
-            const blob = new Blob([iframeContent], { type: 'text/html' });
-            this._iframeObjectUrl = URL.createObjectURL(blob);
-            this.iframe.src = this._iframeObjectUrl;
-        }
-        catch {
-            const encodedContent = encodeURIComponent(iframeContent);
-            this.iframe.src = `data:text/html;charset=utf-8,${encodedContent}`;
-        }
+        // Use `srcdoc` rather than a `blob:` (or `data:`) URL. Both of those give the iframe document
+        // a URL that is out of scope for any http(s) Service Worker registration, so a player that
+        // serves package resources through a Service Worker (CacheStorage, virtual paths) would see
+        // every request made from inside the PCI - module scripts, images, media, stylesheets, fetches -
+        // bypass it and hit the network instead. An `srcdoc` frame inherits this document's URL and
+        // stays controlled by the same Service Worker. It is same-origin either way, and messages are
+        // posted with a `'*'` target origin, so nothing about postMessage changes.
+        this.iframe.srcdoc = iframeContent;
         // Append iframe to component
         this.appendChild(this.iframe);
     }
@@ -676,6 +736,8 @@ export class QtiPortableCustomInteraction extends Interaction {
             dataAttributes: { ...this.dataset },
             interactionModules: this.#getInteractionModules(),
             boundTo: storedState ? null : this.boundTo,
+            responseDeclaration: this.#responseDeclarationForStatus(),
+            status: this.status,
             state: storedState
         };
         this.sendMessageToIframe('initialize', initData);
@@ -730,7 +792,12 @@ export class QtiPortableCustomInteraction extends Interaction {
         this.#pciValidity = null;
         this.#pciCustomValidityMessage = '';
         // Reflect any pre-existing response (e.g. restored session) for validation/completionStatus.
-        this.response = this.responseVariable?.value ?? null;
+        // Don't clobber a value already set via the `response="..."` attribute.
+        const currentResponse = this.response;
+        const hasResponse = Array.isArray(currentResponse) ? currentResponse.length > 0 : !!currentResponse;
+        if (!hasResponse) {
+            this.response = this.responseVariable?.value ?? null;
+        }
         window.addEventListener('message', this.handleIframeMessage);
         this.createIframe();
     }
@@ -747,6 +814,16 @@ export class QtiPortableCustomInteraction extends Interaction {
                 ? `${window.location.origin}${this.dataset.baseUrl}`
                 : this.dataset.baseUrl
             : '';
+        // `data-base-url` names the directory the item was loaded from, so it is also the base every
+        // relative URL inside the interaction should resolve against - the markup's `src`/`href`, the
+        // stylesheets, and whatever the PCI module resolves itself. Anchoring `<base>` at the site
+        // origin instead would send `../assets/x.png` to `/assets/x.png`. Normalise to a trailing
+        // slash: without one the last segment counts as a filename and gets dropped.
+        const iframeBaseHref = iframeBaseUrl
+            ? iframeBaseUrl.endsWith('/')
+                ? iframeBaseUrl
+                : `${iframeBaseUrl}/`
+            : `${window.location.origin}/`;
         const forwardConsole = this.dataset.forwardConsole === 'true';
         const isLocalhost = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';
         const defaultComponentsCdnUrl = isLocalhost
@@ -770,7 +847,7 @@ export class QtiPortableCustomInteraction extends Interaction {
         <head>
           <meta charset="utf-8" />
           <title>QTI PCI Container</title>
-          <base href="${window.location.origin}" />
+          <base href="${iframeBaseHref}" />
           <script type="module">
             import '${componentsCdnUrl}';
           </script>
@@ -892,6 +969,7 @@ export class QtiPortableCustomInteraction extends Interaction {
             // PCI Manager for iframe implementation
             window.PCIManager = {
               pciInstance: null,
+              pciConfig: null,
               container: null,
               markupEl: null,
               propertiesEl: null,
@@ -1117,7 +1195,9 @@ export class QtiPortableCustomInteraction extends Interaction {
                           );
                         },
                         responseIdentifier: config.responseIdentifier,
-                        boundTo: config.boundTo
+                        boundTo: config.boundTo,
+                        responseDeclaration: config.responseDeclaration || undefined,
+                        status: config.status || 'interacting'
                       };
 
                       if (pciInstance.getInstance) {
@@ -1133,6 +1213,9 @@ export class QtiPortableCustomInteraction extends Interaction {
                             restoredState = config.state;
                           }
                         }
+                        // Keep the configuration around next to the instance, it carries the
+                        // status and response declaration this PCI was constructed with.
+                        this.pciConfig = pciConfig;
                         pciInstance.getInstance(dom, pciConfig, restoredState || undefined);
                       } else {
                         this.notifyError('Loaded PCI module has no getInstance().');
@@ -1646,103 +1729,6 @@ export class QtiPortableCustomInteraction extends Interaction {
         </body>
       </html>`;
     }
-    /**
-     * Toggle the display of the correct response
-     * @param responseVariable The response variable containing the correct response
-     * @param show Whether to show or hide the correct response
-     */
-    toggleInternalCorrectResponse(show) {
-        const responseVariable = this.responseVariable;
-        // Store the correct response or clear it based on the show parameter
-        this.correctResponse = show
-            ? responseVariable?.correctResponse
-            : responseVariable.cardinality === 'single'
-                ? ''
-                : [];
-        // Get unique identifiers for this PCI's correct response elements
-        const containerId = `correct-response-container-${this.responseIdentifier}`;
-        // Check the parent element for any existing containers with this ID
-        const existingContainers = this.parentElement?.querySelectorAll(`#${containerId}`);
-        if (existingContainers) {
-            existingContainers.forEach(existingContainer => {
-                existingContainer.remove();
-            });
-        }
-        // Handle the current interaction's state
-        if (show) {
-            // Disable the current interaction when showing correct response
-            this.disable();
-        }
-        else {
-            // Enable the current interaction when hiding correct response
-            this.enable();
-            return; // Exit early, nothing else to do
-        }
-        // If there's no correct response to show, exit
-        if (!show || !responseVariable?.correctResponse) {
-            return;
-        }
-        // Create a container for the correct response viewer
-        const correctResponseContainer = document.createElement('div');
-        correctResponseContainer.id = containerId;
-        correctResponseContainer.className = 'pci-correct-response-container';
-        correctResponseContainer.style.position = 'relative';
-        correctResponseContainer.style.marginTop = '20px';
-        correctResponseContainer.style.border = '2px solid green';
-        correctResponseContainer.style.padding = '16px';
-        correctResponseContainer.style.borderRadius = '4px';
-        correctResponseContainer.style.backgroundColor = 'rgba(0, 128, 0, 0.05)';
-        // Add a label for the correct response
-        const label = document.createElement('div');
-        label.textContent = 'Correct Response:';
-        label.style.fontWeight = 'bold';
-        label.style.marginBottom = '10px';
-        label.style.color = 'green';
-        correctResponseContainer.appendChild(label);
-        // Instead of cloning, we'll create a new instance and copy necessary attributes
-        const correctResponseViewer = document.createElement('qti-portable-custom-interaction');
-        // Copy all attributes from the original PCI
-        Array.from(this.attributes).forEach(attr => {
-            if (attr.name !== 'id' && attr.name !== 'response-identifier') {
-                correctResponseViewer.setAttribute(attr.name, attr.value);
-            }
-        });
-        // Set a unique response identifier to avoid conflicts
-        const originalResponseId = this.responseIdentifier;
-        correctResponseViewer.responseIdentifier = `${originalResponseId}-correct`;
-        // Copy any light DOM content from the original PCI
-        // This includes markup and properties
-        Array.from(this.children).forEach(child => {
-            const clonedChild = child.cloneNode(true);
-            correctResponseViewer.appendChild(clonedChild);
-        });
-        // Store the correct response value
-        const correctResponseValue = responseVariable.correctResponse;
-        // Ensure the correct-response viewer is initialized and then configured in the iframe
-        const originalConnectedCallback = correctResponseViewer.connectedCallback;
-        correctResponseViewer.connectedCallback = function () {
-            originalConnectedCallback.call(this);
-            const applyCorrectResponse = () => {
-                const qtiVariableJSON = this.responseVariablesToQtiVariableJSON(correctResponseValue, responseVariable.cardinality, responseVariable.baseType);
-                this.sendMessageToIframe('setBoundTo', {
-                    [originalResponseId]: qtiVariableJSON
-                });
-                this.sendMessageToIframe('setState', { state: 'review' });
-            };
-            if (this._iframeLoaded) {
-                applyCorrectResponse();
-            }
-            else {
-                this.addEventListener('qti-portable-custom-interaction-loaded', applyCorrectResponse, { once: true });
-            }
-        };
-        // Make sure the viewer is not interactive
-        correctResponseViewer.style.pointerEvents = 'none';
-        // Add the correct response viewer to the container
-        correctResponseContainer.appendChild(correctResponseViewer);
-        // Append the container after this PCI
-        this.after(correctResponseContainer);
-    }
     /**
      * Method to disable the PCI for review mode
      * This can be used when showing the correct response
@@ -1831,6 +1817,9 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'data-use-default-paths' })
 ], QtiPortableCustomInteraction.prototype, "useDefaultPaths", void 0);
+__decorate([
+    property({ type: String, attribute: 'data-status' })
+], QtiPortableCustomInteraction.prototype, "status", void 0);
 __decorate([
     state()
 ], QtiPortableCustomInteraction.prototype, "_errorMessage", void 0);
@@ -1843,6 +1832,6 @@ __decorate([
     state()
 ], QtiPortableCustomInteraction.prototype, "qtiContext", void 0);
 __decorate([
-    state()
+    property({ attribute: 'response', reflect: false, converter: responseAttributeConverter({ emptyAs: null }) })
 ], QtiPortableCustomInteraction.prototype, "response", void 0);
 //# sourceMappingURL=qti-portable-custom-interaction.js.map