@citolab/tspci 2.14.0 → 2.16.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.16.0](https://github.com/Citolab/tspci/compare/v2.15.1...v2.16.0) (2026-11-02)
+
+### Features
+
+* **cli:** enhance watcher to persist until dev server stops ([169759b](https://github.com/Citolab/tspci/commit/169759ba66b43c92661de5a9d8f59fcb42a96f0b))
+
+
+# [2.15.0](https://github.com/Citolab/tspci/compare/v2.14.0...v2.15.0) (2026-10-17)
+
+
+### Features
+
+* **tspci:** correct response from the settings, margins and tools in the authoring descriptor ([86f2628](https://github.com/Citolab/tspci/commit/86f2628b6c71492a9c38db24172ae72701dea645))
+
+
+
+
+
 # [2.14.0](https://github.com/Citolab/tspci/compare/v2.13.0...v2.14.0) (2026-10-14)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@citolab/tspci",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "an opiniated typescript ims-pci builder with tao integration",
   "author": "patrick <patrick.deklein@cito.nl>",
   "repository": {
@@ -65,5 +65,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "d72febca7cea937f77be4cef910a7f2d72fd524f"
+  "gitHead": "1536c32b716a6b6015f95bb3948b0e95ec9c9297"
 }

package/preset/base/AUTHORING.md

@@ -43,7 +43,7 @@ or an object with a `default` plus hints for the author's form:
 | `color` | a colour picker | `"#4b9f4a"` |
 | `colorList` | a list of colour pickers | `"#c91a09, #0055bf"` |
 | `hidden` | nothing (set by the system, not the author) | |
-| `pci` | a "Configure…" button that opens your PCI's own editor (section 5) | whatever your editor writes, as a string |
+| `pci` | a "Configure…" button that opens your PCI's own editor (section 6) | whatever your editor writes, as a string |
 
 A plain value gets an editor from its value: `"true"`/`"false"` a switch, a whole number a number field, the rest a
 text field. `label` is one string or one per language. An authoring system that does not know an editor shows a
@@ -75,7 +75,12 @@ type PropTypes = PciProperties<typeof configProps>; // { width: string; mode: st
   `{ base: { integer: 30 } }` is `single` / `integer`. The package's item declares it, and an authoring system uses it
   for every new item with your PCI.
 - **`score`** lists the scoring your PCI is made for: `MATCH_CORRECT` (the response equals the correct one) and/or
-  `NONE` (not scored, or scored by a person). TAO offers exactly these.
+  `NONE` (not scored, or scored by a person). TAO offers exactly these. The first one is the default.
+- **`correctResponse: "settings"`** says your PCI can tell the correct response from its settings
+  (`getCorrectResponse`, section 4). Leave it out when the correct answer is not in the settings.
+- **`tolerance`** on a `single` response (or on a record field) says which margin a score rule may give it: `range`
+  for an `integer` or `float`, `area` for a `point` (section 4).
+- **`role: "tool"`** (or a `score` of only `["NONE"]`) makes your PCI a tool that is never scored (section 5).
 
 A PCI that reports several values (a moment and a position, say) uses one variable with **record** cardinality:
 QTI binds a PCI to exactly one response variable, and a record has named fields of their own type.
@@ -118,8 +123,58 @@ reports becomes the correct response, or one of several accepted answers. Scorin
   author checks the answer and how a candidate sees it in review.
 - **Margins live in the item, not in the PCI.** A time window or an area is response processing
   (`qti-field-value`, `qti-gte`/`qti-lte`, `qti-inside`) that the authoring system writes from the author's rules.
+  Your PCI reports the raw answer and only says which kind of margin fits, with `tolerance`: `range` (0,75 ± 0,05) or
+  `area` (within 1 of the point (3, 4), in your PCI's own units). Prefer snapping when the answer has steps (a number
+  line in quarters): then the exact match already works and nobody needs a margin.
 
-## 5. Authoring mode: settings your PCI edits itself
+### The correct response from the settings
+
+In a configurable PCI the correct answer usually follows from the settings: 3 of 10 slices coloured → 30. Instead of
+letting the author answer your PCI again after every change, export `getCorrectResponse` next to `getInstance`:
+
+```ts
+const factory: IMSpciFactory<PropTypes> = {
+  typeIdentifier: "myPci",
+  getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+  // the data- properties as strings (a missing one means its default) → what getResponse() reports for the answer
+  getCorrectResponse: (properties) => {
+    const { segments, colored } = pieSettings({ ...configProps, ...properties });
+    return { base: { integer: Math.round((colored / segments) * 100) } };
+  },
+};
+```
+
+and set `"correctResponse": "settings"` in `config.tspci`. An authoring system that supports it fills the item's
+correct response with it and keeps it in line when the author changes a setting; the author can still choose another
+answer. Players never call it. Rules:
+
+- **Parse the settings exactly as your drawing does** (share the function), so the correct answer and what the
+  student sees cannot disagree.
+- **The student must be able to see what is asked.** If a setting changes the correct answer, it must change what the
+  student sees before answering (the fraction to place, the coordinates, the number of slices): a "correct value"
+  setting that is never shown makes the question unanswerable.
+- **Return a response your PCI can show**: `setResponse(getCorrectResponse(p))` on an instance with the same settings
+  must give the same `getResponse()`.
+- **`undefined` when there is no single answer** for these settings (3/5 on a line in steps of 0.25): the authoring
+  system then asks the author.
+- **No DOM, no instance**: it may run on its own, in another frame, before any instance exists.
+
+## 5. A tool: never scored
+
+Not every PCI is a question. A ruler, a protractor, a calculator or a scratch number line helps the student, and its
+use is never scored. Mark it with `"role": "tool"` (or a `score` of only `["NONE"]`) in `config.tspci`:
+
+```json
+"config": { "tspci": { "typeIdentifier": "ruler", "role": "tool", "score": ["NONE"],
+  "response": { "cardinality": "single", "baseType": "string" } } }
+```
+
+QTI binds every PCI to a response variable, so a tool still has one; it may stay `undefined`, or carry the tool's
+state (where the ruler lies) for review. An authoring system shows it as "not scored" and offers no correct answer;
+`correctResponse` and `tolerance` make no sense on a tool, and the build warns about them. Everything else still
+applies: settings, `getState()` and restore, the read-only statuses, keyboard use.
+
+## 6. Authoring mode: settings your PCI edits itself
 
 Some settings cannot be a text field or a number: a shape, a set of areas, a path. Give such a setting
 `"editor": "pci"` and let your PCI edit it. Your PCI then has a second mode, for the item author:
@@ -167,5 +222,8 @@ the property. See `docs/authoring-mode.md` in the tspci repository for the proto
 - [ ] `config.tspci.response` matches what `getResponse()` returns
 - [ ] `getResponse()` gives the same response for the same answer, and `undefined` without one
 - [ ] `setResponse()` / `boundTo` and `status: "solution"` show a given response
+- [ ] when the correct answer follows from the settings: `getCorrectResponse` and `"correctResponse": "settings"`, and
+      every setting that changes the correct answer is visible to the student
+- [ ] a tool: `"role": "tool"`, no correct response
 - [ ] `npm run prod` writes `dist/authoring.json` without warnings
 - [ ] with an authoring mode: delivery works without the `pci` properties (it uses the defaults)

package/preset/base/package.json

@@ -26,7 +26,8 @@
       "score": [
         "MATCH_CORRECT",
         "NONE"
-      ]
+      ],
+      "correctResponse": "settings"
     }
   },
   "source": "src/index.ts"

package/preset/base/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "compilerOptions": {
     "declaration": true,
-    "lib": ["es2017", "dom", "dom.iterable"],
+    "lib": ["es2022", "dom", "dom.iterable"],
     "module": "esnext",
     "moduleResolution": "bundler",
     "removeComments": true,

package/preset/javascript/src/index.js

@@ -12,7 +12,7 @@
 import * as ctx from "qtiCustomInteractionContext"; // provided by the delivery engine at runtime
 import configProps from "./config.json"; // the settings; the build passes only their defaults (AUTHORING.md)
 import style from "./styles.css"; // bundled as a string, added to the shadow root below
-import { escapeHtml, pieSvg } from "./pie.js";
+import { escapeHtml, pieSettings, pieSvg } from "./pie.js";
 // Images are bundled too: `import logo from "./assets/logo.png"` gives a data URL for <img src>.
 
 /** The response for the text in the input: a whole number, or undefined while there is no answer. */
@@ -157,9 +157,22 @@ class PciInstance {
   };
 }
 
+/**
+ * The correct response for a configuration, for authoring systems (config.tspci.correctResponse "settings" in
+ * package.json, AUTHORING.md "Correct answers"): they call it whenever the author changes a setting and fill the item's
+ * correct response with it. It gets the data- properties as strings (a missing one means its default), uses the same
+ * parsing as the drawing, so the two cannot disagree, and returns what getResponse() reports for that answer.
+ * Players never call it, and it must not touch the DOM.
+ */
+function getCorrectResponse(properties) {
+  const { segments, colored } = pieSettings({ ...configProps, ...properties });
+  return { base: { integer: Math.round((colored / segments) * 100) } };
+}
+
 const factory = {
   typeIdentifier: "###___PCI_NAME___###", // the same as config.tspci.typeIdentifier in package.json
   getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+  getCorrectResponse,
 };
 
 // Register with the engine: as an AMD module (qtiCustomInteractionContext), or through the global some engines set.

package/preset/preact/src/index.tsx

@@ -17,6 +17,7 @@ import * as ctx from "qtiCustomInteractionContext"; // provided by the delivery
 import configProps from "./config.json"; // the settings; the build passes only their defaults (AUTHORING.md)
 import style from "./styles.css"; // Tailwind, compiled to a string, added to the shadow root below
 import Interaction from "./interaction";
+import { pieSettings } from "./pie";
 import { Actions, StateModel, initStore } from "./store";
 
 // Like every data- attribute, each setting arrives as a string.
@@ -154,9 +155,22 @@ class PciInstance implements IMSpci<PropTypes> {
   };
 }
 
+/**
+ * The correct response for a configuration, for authoring systems (config.tspci.correctResponse "settings" in
+ * package.json, AUTHORING.md "Correct answers"): they call it whenever the author changes a setting and fill the item's
+ * correct response with it. It gets the data- properties as strings (a missing one means its default), uses the same
+ * parsing as the drawing, so the two cannot disagree, and returns what getResponse() reports for that answer.
+ * Players never call it, and it must not touch the DOM.
+ */
+function getCorrectResponse(properties: Partial<PropTypes>): QtiVariableJSON | undefined {
+  const { segments, colored } = pieSettings({ ...(configProps as unknown as PropTypes), ...properties });
+  return { base: { integer: Math.round((colored / segments) * 100) } };
+}
+
 const factory: IMSpciFactory<PropTypes> = {
   typeIdentifier: "###___PCI_NAME___###", // the same as config.tspci.typeIdentifier in package.json
   getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+  getCorrectResponse,
 };
 
 // Register with the engine: as an AMD module (qtiCustomInteractionContext), or through the global some engines set.

package/preset/preact/src/pie.tsx

@@ -9,12 +9,15 @@ const toInt = (value: string, fallback: number, min: number, max: number) => {
   return Number.isNaN(n) ? fallback : Math.min(max, Math.max(min, n));
 };
 
+/** The pie the settings describe; the limits match the min/max in config.json. */
+export function pieSettings(p: Partial<PropTypes>) {
+  const segments = toInt(p.segments, 10, 2, 24);
+  return { segments, colored: toInt(p.colored, 0, 0, segments), size: toInt(p.size, 200, 100, 400) };
+}
+
 /** A circle of `segments` equal slices, the first `colored` ones filled, clockwise from the top. */
 export const Pie = ({ config }: { config: PropTypes }) => {
-  // the limits match the min/max in config.json
-  const segments = toInt(config.segments, 10, 2, 24);
-  const colored = toInt(config.colored, 0, 0, segments);
-  const size = toInt(config.size, 200, 100, 400);
+  const { segments, colored, size } = pieSettings(config);
   const c = size / 2; // centre
   const r = c - 4; // leave room for the outline
   const point = (i: number) => {

package/preset/typescript/src/index.ts

@@ -20,7 +20,7 @@ import {
 import * as ctx from "qtiCustomInteractionContext"; // provided by the delivery engine at runtime
 import configProps from "./config.json"; // the settings; the build passes only their defaults (AUTHORING.md)
 import style from "./styles.css"; // bundled as a string, added to the shadow root below
-import { escapeHtml, pieSvg } from "./pie";
+import { escapeHtml, pieSettings, pieSvg } from "./pie";
 // Images are bundled too: `import logo from "./assets/logo.png"` gives a data URL for <img src>.
 
 // Like every data- attribute, each setting arrives as a string.
@@ -172,9 +172,22 @@ class PciInstance implements IMSpci<PropTypes> {
   };
 }
 
+/**
+ * The correct response for a configuration, for authoring systems (config.tspci.correctResponse "settings" in
+ * package.json, AUTHORING.md "Correct answers"): they call it whenever the author changes a setting and fill the item's
+ * correct response with it. It gets the data- properties as strings (a missing one means its default), uses the same
+ * parsing as the drawing, so the two cannot disagree, and returns what getResponse() reports for that answer.
+ * Players never call it, and it must not touch the DOM.
+ */
+function getCorrectResponse(properties: Partial<PropTypes>): QtiVariableJSON | undefined {
+  const { segments, colored } = pieSettings({ ...(configProps as unknown as PropTypes), ...properties });
+  return { base: { integer: Math.round((colored / segments) * 100) } };
+}
+
 const factory: IMSpciFactory<PropTypes> = {
   typeIdentifier: "###___PCI_NAME___###", // the same as config.tspci.typeIdentifier in package.json
   getInstance: (dom, config, state) => new PciInstance(dom, config, state),
+  getCorrectResponse,
 };
 
 // Register with the engine: as an AMD module (qtiCustomInteractionContext), or through the global some engines set.

package/preset/typescript/src/pie.ts

@@ -10,7 +10,7 @@ const toInt = (value: string, fallback: number, min: number, max: number) => {
 };
 
 /** The pie the settings describe; the limits match the min/max in config.json. */
-export function pieSettings(p: PropTypes) {
+export function pieSettings(p: Partial<PropTypes>) {
   const segments = toInt(p.segments, 10, 2, 24);
   return {
     segments,

package/public/index.html

@@ -424,6 +424,82 @@
         })
         .catch(() => {});
 
+      // The media slots (authoring.json `markup`, editor "media"): an authoring system with a media bank puts the author's
+      // file in qti-interaction-markup. Here you choose one from disk. It stays in this browser (Cache Storage, per PCI), so
+      // it is still there after the reload every build does; the PCI gets it as a blob: URL (its iframe is of this origin).
+      const devMedia = {}; // slot -> { name, type, url }
+      const mediaSlots = () =>
+        Object.entries(authoringDescriptor?.markup || {}).filter(([, spec]) => (spec?.editor || "media") === "media");
+      const mediaCache = () => caches.open(`tspci-media-${authoringDescriptor?.typeIdentifier || "pci"}`);
+      const mediaKey = (slot) => new URL(`/__tspci_media__/${encodeURIComponent(slot)}`, location.href).href;
+      const mediaLoaded = authoringLoaded
+        .then(async () => {
+          if (!mediaSlots().length || !("caches" in window)) return;
+          const cache = await mediaCache();
+          for (const [slot] of mediaSlots()) {
+            const response = await cache.match(mediaKey(slot));
+            if (!response) continue;
+            const blob = await response.blob();
+            const name = decodeURIComponent(response.headers.get("x-file-name") || slot);
+            devMedia[slot] = { name, type: blob.type, url: URL.createObjectURL(blob) };
+          }
+          renderConfigPanel();
+        })
+        .catch((error) => console.warn("media: could not read Cache Storage", error));
+
+      async function setMedia(slot, file) {
+        const cache = await mediaCache();
+        if (devMedia[slot]) URL.revokeObjectURL(devMedia[slot].url);
+        if (file) {
+          const headers = { "content-type": file.type || "application/octet-stream", "x-file-name": encodeURIComponent(file.name) };
+          await cache.put(mediaKey(slot), new Response(file, { headers }));
+          devMedia[slot] = { name: file.name, type: file.type, url: URL.createObjectURL(file) };
+        } else {
+          await cache.delete(mediaKey(slot));
+          delete devMedia[slot];
+        }
+        renderConfigPanel();
+        refreshCurrentPci();
+      }
+
+      /** The chosen files as the elements an authoring system writes: its `element`, else what `accept` asks for. */
+      function mediaMarkupHtml() {
+        return mediaSlots()
+          .map(([slot, spec]) => {
+            const media = devMedia[slot];
+            if (!media) return "";
+            const element =
+              spec.element || (spec.accept || []).map((type) => type.split("/")[0]).find((kind) => kind === "video" || kind === "audio") || "img";
+            const src = escapeHtmlAttribute(media.url);
+            return element === "img"
+              ? `<img src="${src}" alt="${escapeHtmlAttribute(media.name.replace(/\.[^.]*$/, ""))}">`
+              : `<${element} src="${src}" controls></${element}>`;
+          })
+          .join("");
+      }
+
+      function MediaControls() {
+        const slots = mediaSlots();
+        if (!slots.length) return null;
+        return html`<div class="mb-3 rounded border border-dashed p-2">
+          ${slots.map(([slot, spec]) => {
+            const media = devMedia[slot];
+            return html`<div class="mb-2">
+              <label class="form-label text-muted mb-1" title="markup: ${slot}">${authoringText(spec.label, slot)}${spec.required ? " *" : ""}</label>
+              <input type="file" class="form-control form-control-sm" accept="${(spec.accept || []).join(",")}"
+                onChange="${(e) => e.target.files[0] && setMedia(slot, e.target.files[0])}" />
+              ${media
+                ? html`<div class="d-flex align-items-center gap-2 small mt-1">
+                    <code class="text-truncate" title="${media.name}">${media.name}</code>
+                    <button type="button" class="btn btn-sm btn-link p-0" onClick="${() => setMedia(slot, null)}">remove</button>
+                  </div>`
+                : html`<div class="small text-muted mt-1">None: the markup has no ${spec.element || slot}.</div>`}
+            </div>`;
+          })}
+          <p class="small text-muted mb-0">Goes in <code>qti-interaction-markup</code>, as an authoring system puts it there. The file stays in this browser.</p>
+        </div>`;
+      }
+
       const authoringText = (text, fallback) =>
         !text ? fallback : typeof text === "string" ? text : text.en || Object.values(text)[0] || fallback;
       const toHex = (c) => {
@@ -562,6 +638,7 @@
                     : ""}`
                 : html`No <code>authoring.json</code> yet: build once, or see AUTHORING.md`}
             </p>
+            <${MediaControls} />
             <${AuthoringControls} />
             <fieldset disabled=${!!authoringSession}>
             <form onSubmit="${(e) => e.preventDefault()}">
@@ -930,7 +1007,7 @@
                   <qti-interaction-module id="pci" primary-path="./index"></qti-interaction-module>
                 </qti-interaction-modules>
                 <qti-interaction-markup>
-                  <div data-qti-pci-runtime-host style="height:100%"></div>
+                  <div data-qti-pci-runtime-host style="height:100%"></div>${mediaMarkupHtml()}
                 </qti-interaction-markup>
               </qti-portable-custom-interaction>
             </qti-item-body>
@@ -964,7 +1041,7 @@
         if (typeof globalThis.off !== "function") {
           globalThis.off = () => {};
         }
-        await Promise.all([loadQtiComponents(), authoringLoaded]);
+        await Promise.all([loadQtiComponents(), authoringLoaded, mediaLoaded]);
         loadItem();
       };
     </script>

package/readme.md

@@ -68,6 +68,8 @@ Tailwind is a popular css framework and can be used to give a nice look and feel
 
 preact is a small version of react. You can develop your PCI using hooks and the render function as you are familiar with in react. When preact is selected the cli will also add a store to manage state. This can easily be used to store all user actions in the PCI, and even replay them.
 
+One trap with SVG: Preact writes attributes on SVG elements exactly as you spell them, and SVG attribute names are case-sensitive. `tabIndex` on an SVG element does nothing, so a keyboard user can never reach it; write `tabindex` (on HTML elements both work).
+
 ### specific implementations like TAO.
 
 We also support to create a PCI that can be imported in TAO. Therefor you should use @citolab/tspci-tao.
@@ -131,20 +133,31 @@ have:
   },
   "markup": {},
   "response": { "cardinality": "single", "baseType": "string" },
+  "role": "question",
   "score": ["MATCH_CORRECT", "NONE"]
 }
 ```
 
 The qti3 export declares the item's response from `config.tspci.response` (it used to be `single`/`string` always),
 and the build warns about what an authoring system could not use: an unknown editor, an enum default that is not one
-of its options, a record field without a base type.
+of its options, a record field without a base type, a margin on a type it cannot measure, a correct response on a tool.
 
 **Scoring.** Authors set the correct answer by answering your PCI in a preview: what `getResponse()` reports becomes
 the correct response, or one of several accepted answers, and scoring compares responses. So report the meaning,
 not the route (the same answer must give the same response), report the declared type, return `undefined` without an
 answer, and show a given response (`setResponse`, `boundTo`, and `responseDeclaration.correctResponse` in
 `status: "solution"`). Margins (a time window, an area) live in the item's response processing, which the authoring
-system writes.
+system writes; `tolerance` (`range` for numbers, `area` for points) on the response or a record field says which kind
+fits.
+
+**The correct response from the settings.** When the correct answer follows from the settings (3 of 10 slices → 30),
+the registered object gets `getCorrectResponse(properties)` next to `getInstance`, and `config.tspci.correctResponse`
+is `"settings"`. An authoring system fills the item's correct response with it and keeps it in line when the author
+changes a setting. Every setting that changes the correct answer must be visible to the student, or the question
+cannot be answered. Players never call it; the templates `tspci init` makes have one.
+
+**Tools.** A PCI that helps the student but is never scored (a ruler, a calculator) has `config.tspci.role: "tool"`
+(or a `score` of only `["NONE"]`). It still has a response variable, as QTI requires, but no correct response.
 
 **Authoring mode.** A setting with `"editor": "pci"` is edited by the PCI itself: next to `getInstance`, the registered
 object has `getAuthoringInstance(dom, config)`, which returns `{ getConfig, validate?, destroy? }`. An authoring

package/release-notes.md

@@ -1,3 +1,13 @@
+# 2.15.0
+
+- `getCorrectResponse(properties)` on the registered object (typed on `IMSpciFactory`): the correct response for the item's settings, so an authoring system can fill the correct response and keep it in line when the author changes a setting; `config.tspci.correctResponse: "settings"` puts it in `authoring.json`
+- `tolerance` on a `single` response (it was already on record fields): `range` for an integer or float, `area` for a point, the margin a score rule may give; the build warns when it does not fit the base type
+- tools: `config.tspci.role: "tool"` (or a `score` of only `["NONE"]`) marks a PCI that is never scored, such as a ruler or a calculator; every descriptor now has a `role`, and the build warns about a score, a correct response or a margin on a tool
+- the templates of `tspci init` have a `getCorrectResponse` that shares the drawing's parsing of the settings, and `"correctResponse": "settings"`
+- the generated tsconfig uses `lib: es2022` (was es2017), so `Object.fromEntries`, `replaceAll` and `at()` typecheck
+- fix: `tspci init` with the javascript template kept the preset's name, description and `typeIdentifier` ("myPci") in package.json, which the generated code does not register
+- AUTHORING.md: the correct response from the settings, margins, tools, and a checklist item for settings the student must see; the readme warns that Preact needs `tabindex`, not `tabIndex`, on SVG elements
+
 # 2.12.1
 
 - `tspci init` now writes a tsconfig that is ready for TypeScript 6: an explicit `rootDir` of `./src`, `moduleResolution: "bundler"` instead of the deprecated node10 resolution, `module: "esnext"` and `lib: es2017`

package/src/authoring.js

@@ -17,6 +17,15 @@ export const DESCRIPTOR_FILE = "authoring.json";
  */
 export const PROPERTY_EDITORS = ["text", "textarea", "integer", "number", "boolean", "enum", "color", "colorList", "hidden", "pci"];
 
+/** How an authoring system may find the correct response itself: `settings` = the PCI has getCorrectResponse(properties). */
+export const CORRECT_RESPONSE_SOURCES = ["settings"];
+
+/** The margin a score rule may give a response or a record field: `range` for numbers, `area` for points. */
+export const TOLERANCES = { range: ["integer", "float"], area: ["point"] };
+
+/** `question` is scored; a `tool` (a ruler, a calculator) never counts towards the score. */
+export const ROLES = ["question", "tool"];
+
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 
 /** config.json → the plain defaults the PCI receives (every value a string, as a data- attribute gives it). */
@@ -51,6 +60,17 @@ function toProperty(key, entry, problems) {
   return { editor, default: String(value), ...rest };
 }
 
+/** A margin only fits a base type it can measure: a range on numbers, an area on points. */
+function checkTolerance(where, tolerance, baseType, problems) {
+  if (tolerance === undefined) return;
+  const fits = TOLERANCES[tolerance];
+  if (!fits) {
+    problems.push(`${where}.tolerance: "${tolerance}" is not one of ${Object.keys(TOLERANCES).join(", ")}`);
+  } else if (baseType && !fits.includes(baseType)) {
+    problems.push(`${where}.tolerance: "${tolerance}" needs a base type ${fits.join(" or ")}, not ${baseType}`);
+  }
+}
+
 function checkResponse(response, problems) {
   if (!response) return;
   const cardinality = response.cardinality ?? "single";
@@ -62,12 +82,39 @@ function checkResponse(response, problems) {
     if (!fields.length) problems.push("config.tspci.response: a record needs fields");
     for (const [name, field] of fields) {
       if (!field?.baseType) problems.push(`config.tspci.response.fields.${name}: baseType is missing`);
+      checkTolerance(`config.tspci.response.fields.${name}`, field?.tolerance, field?.baseType, problems);
+    }
+    if (response.tolerance !== undefined) problems.push("config.tspci.response.tolerance: a record has a tolerance per field, not one for all");
+  } else {
+    if (!response.baseType) problems.push("config.tspci.response: baseType is missing");
+    // A margin on a list would mean a margin per value: no authoring system scores that, so only single responses.
+    if (response.tolerance !== undefined && cardinality !== "single") {
+      problems.push(`config.tspci.response.tolerance: only a single response can have one, not ${cardinality}`);
+    } else {
+      checkTolerance("config.tspci.response", response.tolerance, response.baseType, problems);
     }
-  } else if (!response.baseType) {
-    problems.push("config.tspci.response: baseType is missing");
   }
 }
 
+/**
+ * Question or tool, and where the correct response can come from. A tool is never scored: config.tspci.role "tool",
+ * or a score list with only NONE. A tool has no correct response, so correctResponse makes no sense on it.
+ */
+function toRole(tspci, problems) {
+  const scoreOnlyNone = Array.isArray(tspci.score) && tspci.score.length > 0 && tspci.score.every((s) => s === "NONE");
+  const role = tspci.role ?? (scoreOnlyNone ? "tool" : "question");
+  if (!ROLES.includes(role)) problems.push(`config.tspci.role: "${role}" is not one of ${ROLES.join(", ")}`);
+  if (role === "tool" && Array.isArray(tspci.score) && !scoreOnlyNone) {
+    problems.push("config.tspci.score: a tool is never scored, so score can only be [\"NONE\"]");
+  }
+  const source = tspci.correctResponse;
+  if (source !== undefined && !CORRECT_RESPONSE_SOURCES.includes(source)) {
+    problems.push(`config.tspci.correctResponse: "${source}" is not one of ${CORRECT_RESPONSE_SOURCES.join(", ")}`);
+  }
+  if (source !== undefined && role === "tool") problems.push("config.tspci.correctResponse: a tool has no correct response");
+  return { role, correctResponse: CORRECT_RESPONSE_SOURCES.includes(source) && role !== "tool" ? source : undefined };
+}
+
 /**
  * The authoring mode of a PCI: present when a property has editor `pci`. config.tspci.authoring adds a label for the
  * button that opens it and the size the PCI would like for it.
@@ -83,7 +130,8 @@ function toAuthoring(authoring, properties, problems) {
 
 /**
  * The descriptor of a PCI project. `problems` lists what an authoring system could not use (an unknown editor, an
- * enum default that is not an option, a record field without a base type); the build reports them as warnings.
+ * enum default that is not an option, a record field without a base type, a margin on a type it cannot measure, a
+ * correct response on a tool); the build reports them as warnings.
  */
 export function buildDescriptor(packageJson, config) {
   const tspci = packageJson?.config?.tspci ?? {};
@@ -96,6 +144,9 @@ export function buildDescriptor(packageJson, config) {
   const response = tspci.response ?? { cardinality: "single", baseType: "string" };
   checkResponse(response, problems);
   const authoring = toAuthoring(tspci.authoring, properties, problems);
+  const { role, correctResponse } = toRole(tspci, problems);
+  const margins = [response.tolerance, ...Object.values(response.fields ?? {}).map((f) => f?.tolerance)].filter((t) => t !== undefined);
+  if (role === "tool" && margins.length) problems.push("config.tspci.response: a tool is never scored, so a tolerance makes no sense");
 
   return {
     descriptor: {
@@ -106,7 +157,9 @@ export function buildDescriptor(packageJson, config) {
       properties,
       markup: tspci.markup ?? {},
       response,
-      ...(tspci.score ? { score: tspci.score } : {}),
+      role,
+      ...(tspci.score ? { score: tspci.score } : role === "tool" ? { score: ["NONE"] } : {}),
+      ...(correctResponse ? { correctResponse } : {}),
       ...(authoring ? { authoring } : {}),
     },
     problems,

package/src/cli.js

@@ -128,7 +128,10 @@ const watchBuild = (devServer = false, target = "IMS") => {
         result.close();
       }
     });
-    watcher.close();
+    // keep watching until the dev server stops (closing it here cancels the first build)
+    const closeWatcher = () => watcher.close();
+    process.on("SIGINT", closeWatcher);
+    process.on("SIGTERM", closeWatcher);
   });
 };
 
@@ -455,10 +458,8 @@ const run = async () => {
         path.join(destinationFolder, "src"),
         pciName
       );
-      // point to the javascript file
-      const packageJson = path.join(destinationFolder, "package.json");
-      const packageJsonContent = fs.readFileSync(packageJson, "utf8");
-      let packageJsonContentJson = JSON.parse(packageJsonContent);
+      // point to the javascript file. Keep the package.json built above (name, description, typeIdentifier): reading
+      // it from disk again gave every javascript project the preset's "myPci", which its code does not register.
       packageJsonContentJson.source = "src/index.js";
       const newPackageJsonContent = JSON.stringify(packageJsonContentJson, null, 2);
       fs.writeFileSync(packageJson, newPackageJsonContent);

package/types/index.d.ts

@@ -69,10 +69,20 @@ export interface AuthoringResponseField {
   editor?: string;
   label?: AuthoringText;
   /** The kind of margin a score rule may give it: "range" (numbers), "area" (points). */
-  tolerance?: string;
+  tolerance?: AuthoringTolerance;
   [hint: string]: unknown;
 }
 
+/**
+ * The kind of margin a score rule may give a response: "range" (an integer or float between two values, or within a
+ * distance of the correct one), "area" (a point inside a shape, or within a distance of the correct point). The margin
+ * itself is response processing in the item, written by the authoring system; the PCI only says which kind fits.
+ */
+export type AuthoringTolerance = "range" | "area";
+
+/** "question" is scored; a "tool" (a ruler, a protractor, a calculator) never counts towards the score. */
+export type PciRole = "question" | "tool";
+
 /**
  * dist/authoring.json, generated from src/config.json and package.json config.tspci, and shipped next to the bundle.
  * See AUTHORING.md.
@@ -86,10 +96,18 @@ export interface AuthoringDescriptor {
   /** Elements the item puts in qti-interaction-markup, e.g. `{ "video": { "editor": "media", "accept": ["video/*"] } }`. */
   markup: Record<string, { editor: string; element?: string; accept?: string[]; required?: boolean; label?: AuthoringText }>;
   response:
-    | { cardinality: "single" | "multiple" | "ordered"; baseType: string }
+    | { cardinality: "single"; baseType: string; tolerance?: AuthoringTolerance }
+    | { cardinality: "multiple" | "ordered"; baseType: string }
     | { cardinality: "record"; fields: Record<string, AuthoringResponseField> };
+  /** config.tspci.role; a score of only ["NONE"] makes a tool. */
+  role: PciRole;
   /** The response processing templates the PCI is meant for (TAO's score setting), e.g. ["MATCH_CORRECT", "NONE"]. */
   score?: string[];
+  /**
+   * "settings": the registered object has getCorrectResponse(properties), so an authoring system can fill the correct
+   * response from the item's settings (and keep it in line when they change). Never on a tool.
+   */
+  correctResponse?: "settings";
   /** Present when the PCI has an authoring mode: properties with editor "pci", plus config.tspci.authoring. */
   authoring?: AuthoringMode;
 }
@@ -205,8 +223,18 @@ export interface IMSpci<T> {
 export interface IMSpciFactory<T> {
   typeIdentifier: string;
   getInstance: (dom: HTMLElement, configuration: ConfigProperties<T>, state?: string) => IMSpci<T>;
+  /**
+   * Not part of QTI 3: the correct response for these settings, for an authoring system (config.tspci.correctResponse
+   * "settings"). Gets the item's data- properties as strings (a missing one means its default) and returns what
+   * getResponse() reports for the correct answer, or undefined when these settings have no single correct answer.
+   * Players never call it. It must not touch the DOM: it may run without an instance, in another frame.
+   */
+  getCorrectResponse?: PciCorrectResponse<T>;
 }
 
+/** See IMSpciFactory.getCorrectResponse. */
+export type PciCorrectResponse<T> = (properties: Partial<T>) => QtiVariableJSON | undefined;
+
 /**
  * The QTI 3 PCI (the object registered with qtiCustomInteractionContext) extended with an authoring mode:
  * getAuthoringInstance next to getInstance. Delivery engines only know getInstance and never call it, so the PCI works