@citolab/tspci 2.6.3-beta.1 → 2.6.8

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.6.8](/compare/v2.6.7...v2.6.8) (2026-02-02)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
+## [2.6.7](/compare/v2.6.6...v2.6.7) (2026-02-02)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
+## [2.6.6](/compare/v2.6.5...v2.6.6) (2026-02-02)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
+## [2.6.5](/compare/v2.6.3-beta.3...v2.6.5) (2025-04-16)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
+## [2.6.3-beta.3](/compare/v2.6.3-beta.2...v2.6.3-beta.3) (2025-04-16)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
+## [2.6.3-beta.2](/compare/v2.6.3-beta.1...v2.6.3-beta.2) (2025-04-16)
+
+**Note:** Version bump only for package @citolab/tspci
+
+
+
+
+
 ## [2.6.3-beta.1](/compare/v2.6.3-beta.0...v2.6.3-beta.1) (2025-04-14)
 
 **Note:** Version bump only for package @citolab/tspci

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@citolab/tspci",
-  "version": "2.6.3-beta.1",
+  "version": "2.6.8",
   "description": "an opiniated typescript ims-pci builder with tao integration",
   "author": "patrick <patrick.deklein@cito.nl>",
   "repository": "@citolab/tspci",
@@ -14,42 +14,33 @@
   "type": "module",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^28.0.0",
+    "@compodoc/live-server": "^1.2.3",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-image": "^3.0.3",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.3.0",
-    "@rollup/plugin-replace": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.0",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@tailwindcss/nesting": "0.0.0-insiders.565cd3e",
-    "@tailwindcss/postcss": "^4.0.3",
-    "@testing-library/dom": "^10.4.0",
-    "@types/node": "^22.5.5",
-    "@typescript-eslint/eslint-plugin": "^8.9.0",
-    "@typescript-eslint/parser": "^8.9.0",
-    "autoprefixer": "10.4.20",
-    "chalk": "5.3.0",
-    "chokidar": "^4.0.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "autoprefixer": "10.4.23",
+    "chalk": "5.6.2",
+    "chokidar": "^5.0.0",
     "clear": "0.1.0",
-    "figlet": "1.8.0",
-    "inquirer": "12.0.0",
-    "live-server": "^1.2.2",
-    "postcss": "^8.4.47",
-    "postcss-import": "^16.1.0",
-    "rollup": "^4.34.1",
+    "figlet": "1.10.0",
+    "inquirer": "13.2.2",
+    "postcss": "^8.5.6",
+    "postcss-import": "^16.1.1",
+    "rollup": "^4.57.1",
     "rollup-plugin-copy": "^3.5.0",
-    "rollup-plugin-live-server": "^2.0.0",
     "rollup-plugin-livereload": "^2.0.5",
-    "rollup-plugin-node-builtins": "^2.1.2",
-    "rollup-plugin-node-globals": "^1.4.0",
     "rollup-plugin-postcss": "^4.0.2",
-    "rollup-plugin-string": "^3.0.0",
-    "tailwindcss": "^4.1.3"
+    "tailwindcss": "^4.1.18"
   },
-  "resolutions": {
-    "chokidar": "^4.0.0"
-  },
-  "gitHead": "86cdeaf19f50955e56c729ea9fe96ab82d1df171"
+  "gitHead": "8ee09d71856222417e1fc33d22edaf05344c68fe"
 }

package/preset/javascript/src/index.js

@@ -2,144 +2,165 @@ import * as ctx from "qtiCustomInteractionContext";
 import configProps from "./config.json";
 import style from "./styles.css"; // import and bundle this style file ( you can use tailwind and nested css )
 import procenten from "./assets/procenten.png"; // image types are bundled inside the js
-class Pci {
-  /**
-   * @constructor
-   * @param {string} typeIdentifier - The unique identifier for this PCI type.
-   */
-  typeIdentifier; // typeIdentifier is mandatory for all PCI's
-  config; // reference to the interface of the config object which you get when getInstance is called by the player
-  state; // keep a reference to the state
-  shadowdom; // Not mandatory, but its wise to create a shadowroot
-
-  constructor() {
-    /**
-     * @type {string}
-     * @description The unique identifier for this PCI type.
-     */
-    this.typeIdentifier = "###___PCI_NAME___###"; // typeIdentifier is mandatory for all PCI's
-    if (ctx) {
-      ctx.register(this); // we assume the qtiCustomInteractionContext is avaible due to the import above
-    }
-  }
+class PciInstance {
+  typeIdentifier = "###___PCI_NAME___###";
 
-  /**
-   * @method getInstance
-   * @description Creates a new instance of this portable custom interaction.
-   * This method will be called by the qtiCustomInteractionContext.
-   *
-   * @param {HTMLElement} dom - The DOM element to which this PCI is added.
-   * @param {Object<ConfigProperties>} config - The configuration to apply to this PCI.
-   * @param {string} state - A previously saved state to restore the PCI instance.
-   * This state must have been obtained from a prior call to getState for an instance of the same typeIdentifier.
-   */
-  getInstance = (dom, config, state) => {
-    config.properties = { ...configProps, ...config.properties }; // merge current props with incoming
+  constructor(dom, config, stateString) {
+    if (!dom) throw new Error("No DOM Element provided");
+    config.properties = { ...configProps, ...config.properties };
+    this.dom = dom;
     this.config = config;
-    this.state = state ? state : "";
-
     this.shadowdom = dom.attachShadow({ mode: "closed" });
-    this.render();
-    
-    if (this.config.boundTo && Object.keys(this.config.boundTo).length > 0) {
-      const responseIdentifier = Object.keys(this.config.boundTo)[0];
-      const response = this.config.boundTo[responseIdentifier];
-      this.setResponse(response);
+
+    this.state = { value: "", touched: false, customValidity: "" };
+    if (stateString) {
+      try {
+        const parsed = JSON.parse(stateString);
+        this.state.value = typeof parsed?.value === "string" ? parsed.value : "";
+        this.state.touched = parsed?.touched === true;
+        this.state.customValidity =
+          typeof parsed?.customValidity === "string" ? parsed.customValidity : "";
+      } catch {
+        this.state.value = String(stateString);
+        this.state.touched = false;
+      }
     }
 
-    const event = {
-      interaction: this,
-      responseIdentifier: this.config.responseIdentifier,
-      valid: true,
-      value: this.getResponse(),
+    const boundResponse =
+      (this.config.boundTo && this.config.responseIdentifier
+        ? this.config.boundTo[this.config.responseIdentifier]
+        : undefined) ||
+      (this.config.boundTo && Object.keys(this.config.boundTo).length === 1
+        ? this.config.boundTo[Object.keys(this.config.boundTo)[0]]
+        : undefined);
+    if (boundResponse) {
+      this.setResponse(boundResponse);
+    }
+
+    this.onChange = (e) => {
+      const target = e && e.target;
+      if (!target) return;
+      const nextValue = typeof target.value === "string" ? target.value : "";
+      if (nextValue === this.state.value && this.state.touched) return;
+      this.state.value = nextValue;
+      this.state.touched = true;
+      this.dispatchInteractionChanged();
     };
-    // dispatch a custom event to notify the Delivery System that the interaction has changed
-    const interactionChangedEvent = new CustomEvent("qtiInteractionChanged", {
-      detail: event,
-    });
-    this.shadowdom.dispatchEvent(interactionChangedEvent);
-  };
 
-  interactionChanged = () => {
-    const event = {
+    this.render();
+
+    if (this.config.onready) {
+      this.config.onready(this, this.getState());
+    }
+  }
+
+  getInputEl = () => this.shadowdom.querySelector("input[type='number']");
+
+  dispatchInteractionChanged = () => {
+    const detail = {
       interaction: this,
       responseIdentifier: this.config.responseIdentifier,
-      valid: true,
+      valid: this.checkValidity?.() ?? true,
       value: this.getResponse(),
     };
-    // dispatch a custom event to notify the Delivery System that the interaction has changed
-    const interactionChangedEvent = new CustomEvent("qti-interaction-changed", {
-      detail: event,
+    const event = new CustomEvent("qti-interaction-changed", {
+      bubbles: true,
+      cancelable: true,
+      detail,
     });
-    this.dom.dispatchEvent(interactionChangedEvent);
+    this.dom.dispatchEvent(event);
   };
 
-  setResponse = (response) => {
-    // TODO restore the response
-    // Get the actual value by the variable type like:
-    // - response?.base?.string or response?.base?.integer
-  }
-
   render = () => {
-    this.shadowdom.addEventListener("change", (e) => {
-      const value = e.target.value;
-      this.state = value;
-      this.interactionChanged();
-    });
     this.shadowdom.innerHTML = `<div class="pci-container">
       <h1>${this.config.properties.title}</h1>
       <div class="body">
-        <img width="${+this.config.properties.width}" height="${+this.config.properties.height}" src="${procenten}" />
+        <img width="${+this.config.properties.width}" height="${+this.config
+      .properties.height}" src="${procenten}" />
       </div>
       <div class="interaction">
-        <label for="tentacles">${this.config.properties.prompt}</label>
-        <input type="number" value="${this.state}" min="0" max="100">%
+        <label>${this.config.properties.prompt}</label>
+        <input type="number" value="${this.state.value}" min="0" max="100">%
       </div>
     </div>`;
     const css = document.createElement("style");
     css.innerHTML = style;
     this.shadowdom.appendChild(css);
+
+    const input = this.getInputEl();
+    if (input) {
+      if (this.state.customValidity) input.setCustomValidity(this.state.customValidity);
+      input.addEventListener("input", this.onChange);
+      input.addEventListener("change", this.onChange);
+    }
+  };
+
+  setResponse = (response) => {
+    let next = "";
+    if (response && response.base) {
+      if (typeof response.base.integer === "number") next = String(response.base.integer);
+      else if (typeof response.base.string === "string") next = response.base.string;
+    }
+    this.state.value = next;
+    this.state.touched = true;
+    const input = this.getInputEl();
+    if (input) input.value = next;
   };
 
-  /**
-   * @method getResponse
-   * @description Retrieves the value to assign to the bound QTI response variable.
-   *
-   * @returns {Object} - The response value.
-   */
   getResponse = () => {
-    const response = this.state === null || this.state === undefined ? undefined : { base: { integer: this.state } };
-    return response;
+    if (!this.state.touched) return undefined;
+    const trimmed = String(this.state.value == null ? "" : this.state.value).trim();
+    if (!trimmed) return undefined;
+    const asNumber = Number(trimmed);
+    if (!Number.isFinite(asNumber)) return undefined;
+    return { base: { integer: Math.trunc(asNumber) } };
   };
 
-  /**
-   * @method getState
-   * @description Retrieves the current state of this PCI. This state can be passed to getInstance to restore the instance later.
-   *
-   * @returns {string} - The current state of the PCI.
-   */
-  getState = () => this.state.toString();
-
-
-  /**
-   * @method resetResponse
-   * @description Can set the response to a previously stored state.
-   * Also a way in TAO to show the correct response in the score-editor.
-   * @param {QtiVariableJSON} response - The response to set.
-   * @returns {void}
-   * @example
-   * const response = {
-   *   base: {
-   *     integer: 100
-   *   }
-   * };
-   */
-  setResponse = (response) => { }
-  /**
-   * @method oncompleted
-   * @description called when the PCI is completed.
-   */
-  oncompleted = () => {};
+  getState = () => JSON.stringify(this.state);
+
+  checkValidity = () => {
+    const input = this.getInputEl();
+    if (!input) return undefined;
+    return input.checkValidity();
+  };
+
+  reportValidity = () => {
+    const input = this.getInputEl();
+    if (!input) return undefined;
+    return input.reportValidity();
+  };
+
+  setCustomValidity = (message) => {
+    this.state.customValidity = message == null ? "" : String(message);
+    const input = this.getInputEl();
+    if (input) input.setCustomValidity(this.state.customValidity);
+  };
+
+  getCustomValidity = () => this.state.customValidity ?? "";
+
+  oncompleted = () => {
+    const input = this.getInputEl();
+    if (input) {
+      input.removeEventListener("input", this.onChange);
+      input.removeEventListener("change", this.onChange);
+    }
+  };
+}
+
+const factory = {
+  typeIdentifier: "###___PCI_NAME___###",
+  getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+};
+
+const engineContext =
+  ctx && typeof ctx.register === "function"
+    ? ctx
+    : typeof window !== "undefined" && window.qtiCustomInteractionContext
+      ? window.qtiCustomInteractionContext
+      : undefined;
+
+if (engineContext && typeof engineContext.register === "function") {
+  engineContext.register(factory);
 }
 
-export default new Pci();
+export default factory;

package/preset/preact/src/index.tsx

@@ -1,77 +1,97 @@
 import "preact/debug";
 import { render } from "preact";
-import { IStore } from "@citolab/preact-store";
+import { IStore, Listener } from "@citolab/preact-store";
 import * as ctx from "qtiCustomInteractionContext";
 import Interaction from "./interaction";
 import style from "./styles.css";
-import { ConfigProperties, IMSpci, QtiInteractionChangedDetail, QtiVariableJSON } from "@citolab/tspci";
+import { ConfigProperties, IMSpci, IMSpciFactory, QtiInteractionChangedDetail, QtiVariableJSON } from "@citolab/tspci";
 import configProps from "./config.json";
 import { StateModel, initStore } from "./store";
 
 type PropTypes = typeof configProps;
 
-class App implements IMSpci<PropTypes> {
-  typeIdentifier = "###___PCI_NAME___###"; // typeIdentifier is mandatory for all PCI's
-  config: ConfigProperties<PropTypes>; // reference to the interface of the config object which you get when getInstance is called by the player
-  state: string; // keep a reference to the state
-  shadowdom: ShadowRoot; // Not mandatory, but its wise to create a shadowroot
-  store: IStore<StateModel>;
-
-  private logActions: { type: string; payload: unknown }[] = []; // optional logActions
-  private initialState: StateModel = { input: undefined }; // optional initial state
-  constructor() {
-    if (ctx) {
-      ctx.register(this);
-    }
-  }
+type PciStoredState = {
+  state: StateModel;
+  log: { type: string; payload: unknown; timestamp?: number }[];
+};
+
+class PciInstance implements IMSpci<PropTypes> {
+  typeIdentifier = "###___PCI_NAME___###";
+  private config: ConfigProperties<PropTypes>;
+  private dom: HTMLElement;
+  private shadowdom: ShadowRoot;
+  private store: IStore<StateModel>;
+  private storeListener: Listener<StateModel>;
+  private previousResponseJson: string = "";
+  private initialState: StateModel = { input: undefined };
 
-  getInstance = (dom: HTMLElement, config: ConfigProperties<PropTypes>, stateString: string) => {
-    config.properties = { ...configProps, ...config.properties }; // merge current props with incoming
+  constructor(dom: HTMLElement, config: ConfigProperties<PropTypes>, stateString?: string) {
+    if (!dom) throw new Error("No DOM Element provided");
+    config.properties = { ...configProps, ...config.properties };
+    this.dom = dom;
     this.config = config;
-    if (!dom) {
-      throw new Error("No DOM Element provided");
+    this.shadowdom = dom.attachShadow({ mode: "closed" });
+
+    let restoreData: PciStoredState | undefined;
+    if (stateString) {
+      try {
+        const parsed = JSON.parse(stateString) as Partial<PciStoredState>;
+        if (parsed && parsed.state && Array.isArray(parsed.log)) {
+          restoreData = { state: parsed.state as StateModel, log: parsed.log as PciStoredState["log"] };
+        }
+      } catch {
+        // ignore
+      }
     }
-    this.logActions = stateString ? JSON.parse(stateString).log : [];
+
     this.store = initStore(this.initialState);
-    try {
-      const restoredState = stateString ? JSON.parse(stateString) : null;
-      if (restoredState) {
-        this.store.restoreState(restoredState?.state, this.logActions);
-      }
-    } catch (error) {
-      console.log(error);
+    if (restoreData) {
+      this.store.restoreState(restoreData.state, restoreData.log);
     }
 
-    this.shadowdom = dom.attachShadow({ mode: "closed" });
+    const boundResponse =
+      this.config.boundTo?.[this.config.responseIdentifier] ??
+      (this.config.boundTo && Object.keys(this.config.boundTo).length === 1
+        ? this.config.boundTo[Object.keys(this.config.boundTo)[0]]
+        : undefined);
+    if (boundResponse) {
+      this.setResponse?.(boundResponse);
+    }
 
-    this.store.subscribe(() => {
-      const event: QtiInteractionChangedDetail = {
+    this.render();
+
+    if (this.config.onready) {
+      this.config.onready(this, this.getState());
+    }
+
+    let isFirst = true;
+    this.storeListener = () => {
+      if (isFirst) {
+        isFirst = false;
+        this.previousResponseJson = JSON.stringify(this.getResponse() ?? null);
+        return;
+      }
+      const nextJson = JSON.stringify(this.getResponse() ?? null);
+      if (nextJson === this.previousResponseJson) return;
+      this.previousResponseJson = nextJson;
+
+      const detail: QtiInteractionChangedDetail = {
         interaction: this,
         responseIdentifier: this.config.responseIdentifier,
         valid: true,
         value: this.getResponse(),
       };
-      // dispatch a custom event to notify the Delivery System that the interaction has changed
-      const interactionChangedEvent = new CustomEvent("qti-interaction-changed", {
-        detail: event,
+      const evt = new CustomEvent("qti-interaction-changed", {
+        bubbles: true,
+        cancelable: true,
+        detail,
       });
-      dom.dispatchEvent(interactionChangedEvent);
-    });
-
-    this.render();
-
-    if (this.config.boundTo && Object.keys(this.config.boundTo).length > 0) {
-      const responseIdentifier = Object.keys(this.config.boundTo)[0];
-      const response = this.config.boundTo[responseIdentifier];
-      this.setResponse(response);
-    }
-
-    if (this.config.onready) {
-      this.config.onready(this);
-    }
-  };
+      this.dom.dispatchEvent(evt);
+    };
+    this.store.subscribe(this.storeListener);
+  }
 
-  render = () => {
+  private render = () => {
     render(null, this.shadowdom);
     const css = document.createElement("style");
     css.innerHTML = style;
@@ -80,28 +100,51 @@ class App implements IMSpci<PropTypes> {
   };
 
   setResponse = (response: QtiVariableJSON) => {
-    // TODO restore the response
-    // Get the actual value by the variable type like:
-    // - response?.base?.string or response?.base?.integer
-  }
-
+    const next =
+      typeof response?.base?.integer === "number"
+        ? response.base.integer
+        : typeof response?.base?.string === "string"
+          ? Number(response.base.string)
+          : undefined;
+    if (typeof next !== "number" || !Number.isFinite(next)) return;
+    this.store.dispatch({ type: "SET_INPUT", payload: { input: Math.trunc(next) } });
+  };
 
   getState = () =>
     JSON.stringify({
       state: this.store.getState(),
       log: this.store.getActions(),
-    });
+    } satisfies PciStoredState);
 
   getResponse = () => {
-    const state = this.store?.getState()?.input || undefined;
-    if (state === undefined) return undefined;
-    return {
-      base: {
-        integer: this.store.getState().input,
-      },
-    } as QtiVariableJSON;
-  }
-  oncompleted = () => { };
+    const value = this.store.getState().input;
+    if (value === undefined) return undefined;
+    return { base: { integer: value } } as QtiVariableJSON;
+  };
+
+  oncompleted = () => {
+    if (this.storeListener) {
+      this.store.unsubscribe(this.storeListener);
+    }
+    render(null, this.shadowdom);
+  };
+}
+
+const factory: IMSpciFactory<PropTypes> = {
+  typeIdentifier: "###___PCI_NAME___###",
+  getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+};
+
+const engineContext =
+  ctx && typeof (ctx as unknown as { register?: unknown }).register === "function"
+    ? (ctx as unknown as { register: (f: IMSpciFactory<PropTypes>) => void })
+    : typeof window !== "undefined" && (window as unknown as { qtiCustomInteractionContext?: unknown }).qtiCustomInteractionContext
+      ? ((window as unknown as { qtiCustomInteractionContext: { register: (f: IMSpciFactory<PropTypes>) => void } })
+          .qtiCustomInteractionContext as { register: (f: IMSpciFactory<PropTypes>) => void })
+      : undefined;
+
+if (engineContext) {
+  engineContext.register(factory);
 }
 
-export default new App();
+export default factory;

package/preset/typescript/src/index.ts

@@ -1,4 +1,10 @@
-import { ConfigProperties, IMSpci, QtiInteractionChangedDetail, QtiVariableJSON } from "@citolab/tspci";
+import {
+  ConfigProperties,
+  IMSpci,
+  IMSpciFactory,
+  QtiInteractionChangedDetail,
+  QtiVariableJSON,
+} from "@citolab/tspci";
 import * as ctx from "qtiCustomInteractionContext";
 import configProps from "./config.json";
 import Interaction from "./interaction"; // import and bundle this interaction file
@@ -8,94 +14,177 @@ import procenten from "./assets/procenten.png"; // image types are bundled insid
 // Configuration
 type PropTypes = typeof configProps;
 
-class Pci implements IMSpci<PropTypes> {
-  typeIdentifier = "###___PCI_NAME___###"; // typeIdentifier is mandatory for all PCI's
-  config: ConfigProperties<PropTypes>; // reference to the interface of the config object which you get when getInstance is called by the player
-  state: string; // keep a reference to the state
-  shadowdom: ShadowRoot | Element; // Not mandatory, but its wise to create a shadowroot
-  dom: HTMLElement;
+type PciState = {
+  value: string;
+  touched: boolean;
+  customValidity?: string;
+};
 
-  constructor() {
-    if (ctx) {
-      ctx.register(this); // we assume the qtiCustomInteractionContext is avaible due to the import above
+class PciInstance implements IMSpci<PropTypes> {
+  typeIdentifier = "###___PCI_NAME___###";
+  private config: ConfigProperties<PropTypes>;
+  private dom: HTMLElement;
+  private shadowdom: ShadowRoot;
+  private state: PciState;
+  private onChange: (e: Event) => void;
+
+  constructor(dom: HTMLElement, config: ConfigProperties<PropTypes>, stateString?: string) {
+    if (!dom) throw new Error("No DOM Element provided");
+    config.properties = { ...configProps, ...config.properties };
+    this.dom = dom;
+    this.config = config;
+    this.shadowdom = dom.attachShadow({ mode: "closed" });
+
+    this.state = { value: "", touched: false };
+    if (stateString) {
+      try {
+        const parsed = JSON.parse(stateString) as Partial<PciState>;
+        this.state = {
+          value: typeof parsed.value === "string" ? parsed.value : "",
+          touched: parsed.touched === true,
+          customValidity: typeof parsed.customValidity === "string" ? parsed.customValidity : undefined,
+        };
+      } catch {
+        this.state = { value: typeof stateString === "string" ? stateString : "", touched: false };
+      }
     }
-  }
 
-  // First in the lifecycle of a PCI, this method is called with the domElement ( usually qti-interaction-markup ) where we can add our dom tree.
-  // config is the configuration object which has an onready
-  getInstance = (dom: HTMLElement, config: ConfigProperties<PropTypes>, state: string) => {
-    config.properties = { ...configProps, ...config.properties }; // merge current props with incoming
-    this.config = config;   
-    this.state = state ? state : "";
-    if (!dom) {
-      throw new Error("No DOM Element provided");
+    const boundResponse =
+      this.config.boundTo?.[this.config.responseIdentifier] ??
+      (this.config.boundTo && Object.keys(this.config.boundTo).length === 1
+        ? this.config.boundTo[Object.keys(this.config.boundTo)[0]]
+        : undefined);
+    if (boundResponse && (boundResponse.base || boundResponse.list || boundResponse.record)) {
+      this.setResponse?.(boundResponse);
     }
-    this.shadowdom = dom.attachShadow({ mode: "closed" });
-    this.dom = dom;
+
+    this.onChange = (e: Event) => {
+      const target = e.target as HTMLInputElement | null;
+      if (!target) return;
+      const nextValue = target.value ?? "";
+      if (nextValue === this.state.value && this.state.touched) return;
+      this.state = { ...this.state, value: nextValue, touched: true };
+      this.dispatchInteractionChanged();
+    };
 
     this.render();
 
-    if (this.config.boundTo && Object.keys(this.config.boundTo).length > 0) {
-      const responseIdentifier = Object.keys(this.config.boundTo)[0];
-      const response = this.config.boundTo[responseIdentifier];
-      this.setResponse(response);
+    if (this.config.onready) {
+      this.config.onready(this, this.getState());
     }
+  }
 
-    config.onready(this);
-  };
-
-  setResponse = (response: QtiVariableJSON) => {
-    // TODO restore the response
-    // Get the actual value by the variable type like:
-    // - response?.base?.string or response?.base?.integer
+  private getInputEl(): HTMLInputElement | null {
+    return this.shadowdom.querySelector("input[type='number']");
   }
 
-  private interactionChanged = () => {
-    const event: QtiInteractionChangedDetail = {
+  private dispatchInteractionChanged() {
+    const detail: QtiInteractionChangedDetail = {
       interaction: this,
       responseIdentifier: this.config.responseIdentifier,
-      valid: true,
+      valid: this.checkValidity?.() ?? true,
       value: this.getResponse(),
     };
-    // dispatch a custom event to notify the Delivery System that the interaction has changed
-    const interactionChangedEvent = new CustomEvent("qti-interaction-changed", {
-      detail: event,
+    const event = new CustomEvent("qti-interaction-changed", {
+      bubbles: true,
+      cancelable: true,
+      detail,
     });
-    this.dom.dispatchEvent(interactionChangedEvent);
-  };
+    this.dom.dispatchEvent(event);
+  }
 
-  private render = () => {
-    this.shadowdom.addEventListener("change", (e: Event) => {
-      const value = (e.target as HTMLInputElement)?.value || "";
-      this.state = value;
-      this.interactionChanged();
-    });
+  private render() {
     this.shadowdom.innerHTML = `<div class="pci-container">
       <h1>${this.config.properties.title}</h1>
       <div class="body">
-        <img width="${+this.config.properties.width}" height="${+this.config.properties.height}" src="${procenten}" />
+        <img width="${+this.config.properties.width}" height="${+this.config
+      .properties.height}" src="${procenten}" />
       </div>
       <div class="interaction">
-        <label for="tentacles">${this.config.properties.prompt}</label>
-        <input type="number" value="${this.state}" min="0" max="100">%
+        <label>${this.config.properties.prompt}</label>
+        <input type="number" value="${this.state.value}" min="0" max="100">%
       </div>
     </div>`;
+
     const css = document.createElement("style");
     css.innerHTML = style;
     this.shadowdom.appendChild(css);
+
+    const input = this.getInputEl();
+    if (input) {
+      if (this.state.customValidity) input.setCustomValidity(this.state.customValidity);
+      input.addEventListener("input", this.onChange);
+      input.addEventListener("change", this.onChange);
+    }
+  }
+
+  setResponse = (response: QtiVariableJSON) => {
+    const next =
+      typeof response?.base?.integer === "number"
+        ? String(response.base.integer)
+        : typeof response?.base?.string === "string"
+          ? response.base.string
+          : "";
+    this.state = { ...this.state, value: next, touched: true };
+    const input = this.getInputEl();
+    if (input) input.value = next;
   };
 
   getResponse = () => {
-    const response =
-      this.state === null || this.state === undefined
-        ? undefined
-        : ({ base: { integer: this.state } } as QtiVariableJSON);
-    return response;
+    if (!this.state.touched) return undefined;
+    const trimmed = (this.state.value ?? "").toString().trim();
+    if (!trimmed) return undefined;
+    const asNumber = Number(trimmed);
+    if (!Number.isFinite(asNumber)) return undefined;
+    return { base: { integer: Math.trunc(asNumber) } } as QtiVariableJSON;
+  };
+
+  getState = () => JSON.stringify(this.state);
+
+  checkValidity = () => {
+    const input = this.getInputEl();
+    if (!input) return undefined;
+    return input.checkValidity();
+  };
+
+  reportValidity = () => {
+    const input = this.getInputEl();
+    if (!input) return undefined;
+    return input.reportValidity();
   };
 
-  getState = () => this.state.toString();
+  setCustomValidity = (message: string) => {
+    this.state = { ...this.state, customValidity: message };
+    const input = this.getInputEl();
+    if (input) input.setCustomValidity(message);
+  };
+
+  getCustomValidity = () => this.state.customValidity ?? "";
+
+  oncompleted = () => {
+    const input = this.getInputEl();
+    if (input) {
+      input.removeEventListener("input", this.onChange);
+      input.removeEventListener("change", this.onChange);
+    }
+  };
+}
+
+const factory: IMSpciFactory<PropTypes> = {
+  typeIdentifier: "###___PCI_NAME___###",
+  getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+};
+
+const engineContext =
+  ctx && typeof (ctx as unknown as { register?: unknown }).register === "function"
+    ? (ctx as unknown as { register: (f: IMSpciFactory<PropTypes>) => void })
+    : typeof window !== "undefined" && (window as unknown as { qtiCustomInteractionContext?: unknown }).qtiCustomInteractionContext
+      ? ((window as unknown as { qtiCustomInteractionContext: { register: (f: IMSpciFactory<PropTypes>) => void } })
+          .qtiCustomInteractionContext as { register: (f: IMSpciFactory<PropTypes>) => void })
+      : undefined;
 
-  oncompleted = () => {};
+if (engineContext) {
+  engineContext.register(factory);
 }
 
-export default new Pci();
+export default factory;

package/readme.md

@@ -97,38 +97,34 @@ Add the following PCI in the src folder `index.ts`
 
 ```ts
 // src/index.ts
-import { ConfigProperties, IMSpci } from "@citolab/tspci";
-import * as ctx from "qtiCustomInteractionContext";
-
-class Pci implements IMSpci<{}> {
-  typeIdentifier = "HelloWorld"; // same as in package.json
-  shadowdom: ShadowRoot;
-
-  constructor() {
-    ctx && ctx.register(this);
-  }
-
-  getInstance = (dom: HTMLElement, config: ConfigProperties<any>, state: string) => {
-    this.shadowdom = dom.attachShadow({ mode: "closed" });
-    this.render();
-    config.onready(this);
-  };
-
-  private render = () => {
-    this.shadowdom.innerHTML = `<div>Hello-World</div>`;
-  };
-
-  getResponse = () => {
-    return null;
-  };
-
-  getState = () => null;
-
-  setResponse = () => {
-    
-  }
-}
-export default new Pci();
+	import { ConfigProperties, IMSpci, IMSpciFactory } from "@citolab/tspci";
+	import * as ctx from "qtiCustomInteractionContext";
+
+	class PciInstance implements IMSpci<{}> {
+	  typeIdentifier = "HelloWorld"; // same as in package.json
+	  private shadowdom: ShadowRoot;
+
+	  constructor(dom: HTMLElement, config: ConfigProperties<{}>, state?: string) {
+	    this.shadowdom = dom.attachShadow({ mode: "closed" });
+	    this.render();
+	    config.onready(this, this.getState());
+	  }
+
+	  private render = () => {
+	    this.shadowdom.innerHTML = `<div>Hello-World</div>`;
+	  };
+
+	  getResponse = () => undefined;
+	  getState = () => JSON.stringify({ v: 1 });
+	}
+
+	const factory: IMSpciFactory<{}> = {
+	  typeIdentifier: "HelloWorld",
+	  getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+	};
+
+	ctx && ctx.register(factory);
+	export default factory;
 ```
 
 Add this in your root project: `global.d.ts` file
@@ -136,7 +132,7 @@ Add this in your root project: `global.d.ts` file
 ```ts
 // global.d.ts
 declare module "qtiCustomInteractionContext" {
-  const register: { register: (PortableInteraction) => void };
+  const register: { register: (factory: { typeIdentifier: string; getInstance: Function }) => void };
   export = register;
 }
 ```
@@ -343,8 +339,9 @@ Also used in the TAO export for configuring PCIs in TAO
   // add to types
   + private config: ConfigProperties<PropTypes>;
 
+  // in your factory.getInstance(...) (or instance constructor):
   getInstance = (dom: HTMLElement, config: ConfigProperties<PropTypes>, stateString: string) => {
-  + config.properties = { ...configProps, ...config.properties }; // merge our props with players
+  + config.properties = { ...configProps, ...config.properties }; // merge our props with the player's
   + this.config = config;
 
   // destructure props for use in PCI

package/src/rollup-plugin-live-server.js

@@ -3,7 +3,7 @@
 // https://www.npmjs.com/package/rollup-plugin-live-server
 // const ls = require("live-server");
 
-import ls from "live-server";
+import ls from "@compodoc/live-server";
 
 export function liveServer(options = {}) {
   const directories = options.directories || [];

package/types/index.d.ts

@@ -28,17 +28,6 @@ export interface ConfigProperties<T> {
 export interface IMSpci<T> {
   typeIdentifier: string;
 
-  /** @access public
-   *  @method getInstance Create a new instance of this portable custom interaction
-   *  Will be called by the qtiCustomInteractionContext
-   *  @param {DOM Element} dom - the DOM Element this PCI is being added to
-   *  @param {Object} configuration - the configuration to apply to this PCI
-   *  @param {String} state - a previous saved state to apply to this instance.
-   *  This must have been obtained from a prior call to getState on an
-   *  instance of this type (same typeIdentifier)
-   */
-  getInstance: (dom: HTMLElement, configuration: ConfigProperties<T>, state: string) => void;
-
   /** @access public
    * @method getResponse
    * @return {Object} - the value to assign to the bound QTI response variable
@@ -52,8 +41,17 @@ export interface IMSpci<T> {
    */
   getState: () => string;
   oncompleted?: () => void;
-  setResponse?: (response: QtiVariableJSON) => void; // No IMS specification for this, but best option to set the response when bound to a QTI variable
-  destroy?: () => void; // Not used in IMS and not in TAO implementation, so not used here (optional)
+  checkValidity?: () => boolean | undefined;
+  reportValidity?: () => boolean | undefined;
+  setCustomValidity?: (message: string) => void;
+  getCustomValidity?: () => string;
+  setResponse?: (response: QtiVariableJSON) => void; // Not in the QTI 3.0 PCI instance interface, but used by some delivery engines/tools
+  destroy?: () => void; // Not used in QTI 3.0, but kept for compatibility
+}
+
+export interface IMSpciFactory<T> {
+  typeIdentifier: string;
+  getInstance: (dom: HTMLElement, configuration: ConfigProperties<T>, state?: string) => IMSpci<T>;
 }
 
 export interface directedPair {