@memizy/oqse 1.0.0-rc.5 → 1.0.0-rc.7

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog of @memizy/oqse
+
+The format itself has its own changelog at the end of [oqse.md](https://github.com/memizy/memizy/blob/main/packages/oqse/oqse.md#version-10-2026-10-14) (OQSE 1.0, 2026-10-14). This file lists the releases of the npm package.
+
+## 1.0.0-rc.7 (2026-10-16)
+
+Forward compatibility of OQSE 1.0 (see the "Version 1.0" changelog in `oqse.md`), checked by `forwardCompat.test.ts` with files of a "later 1.x version".
+
+* **Must-understand properties**: `mustUnderstand` on any item lists properties it depends on; an item that needs a property this version does not know goes to `unsupportedItems` (warning `MUST_UNDERSTAND`), and `checkAnswer` refuses it instead of grading it wrong. `loadOQSEFile` / `safeValidateOQSEFile` / `validateOQSEFile` take `{ understood }` (properties the application supports itself, e.g. its own `x-` ones). `missingMustUnderstand(item, understood?)`; `KNOWN_ITEM_PROPERTIES` (generated from the schemas at build time, so `checkAnswer` needs no Zod). This is how a later 1.x may change how items are checked.
+* Warning `REVEALING_CHOICE_ID` for choice IDs that name the answer (`correct`, `wrong_1`…): learners can see IDs.
+* A set may hold 50,000 items (`MAX_ITEMS`, was 10,000); `MAX_JSON_DEPTH`.
+* Spec: an item is identified by `meta.id` + `item.id`; custom names SHOULD carry the vendor (`x-<vendor>-…`). Zod: `parse` / `safeParse` of the exported schemas are covered by semver, their Zod-specific API is not.
+* Open values: `MediaObject.type`, `subtitles[].kind`, `pedagogy.bloomLevel` / `cognitiveLoad`, `SourceMaterial.kind`, OQSEM `studyMode` / `questionDensity` accept values of later versions (`OpenValueSchema`, warning `UNKNOWN_VALUE`); `MEDIA_TYPES`, `SOURCE_KINDS`, `SUBTITLE_KINDS`, `BLOOM_LEVELS`, `COGNITIVE_LOADS` list the known ones; the type `OpenValue<T>`. Before, a new media type or source type made the whole set unreadable and a new Bloom level removed the question.
+* Items of unknown types: `loadOQSEFile` and `safeValidateOQSEFile` return them unchanged in `unsupportedItems` (a warning, no longer an error in strict validation); `withUnsupportedItems(file, unsupportedItems)` puts them back for saving.
+* `SourceMaterial`: `kind`, `url`, `doi`, `isbn`, `set`, `mimeType` replace `type` + `value` (`SourceMaterialType` / `SourceMaterialTypeSchema` removed; `SourceKind`, `SOURCE_KINDS`); `SourceReference.itemId`. Sets of the release candidates are converted by the repository tool `scripts/migrate-oqse` (the library itself does not carry the old shape: such a source loads as a source cited by its title); every source is validated on its own, so a bad source no longer makes the set unreadable (`INVALID_SOURCE`); `SOURCE_WITHOUT_LOCATOR` warns about a source cited by title only; an `itemId` into this very set must exist.
+* OQSEP: `starred`, `lastAnswer.answer` (≤ 4 KB, `MAX_LAST_ANSWER_BYTES`); all OQSEP schemas keep unknown keys (they used to drop them, and the JSON Schema had `additionalProperties: false`).
+* OQSEM: `capabilities.types` / `actions` accept lowercase names of later versions; unknown keys and asset categories are kept. OQSEH: unknown keys are kept.
+* `checkCompatibility` does not report media of an unknown type as unsupported (they fall back to a link).
+* Tolerant reading of real data (each case made a whole set unreadable before): BCP 47 tags with numeric regions and variants (`es-419`, `de-CH-1996`) and `cs_CZ` converted to `cs-CZ` (warning `LANGUAGE_NORMALIZED`); fractions of a second of any length (`…00.123456Z`, as databases write them) in sets and progress files; subtitles from any URI; an invalid optional `meta` field or one broken entry of `assets`, `tagDefinitions`, `translations`… is removed with an error (`INVALID_META_FIELD`) instead of refusing the set; the nesting limit is 32 levels for the whole file (`MAX_JSON_DEPTH`; it was 10 from the root, so a moderately deep `appSpecific` broke the set).
+* OQSEP record keys are item IDs, not only UUIDs (generated items).
+* The specification fixes for 1.x what older applications could not handle growing: size limits and ranges of scales, the HTML tags allowed without `html`, the formats of IDs, dates and language tags.
+
+## 1.0.0-rc.6 (2026-10-14)
+
+Release candidate of OQSE 1.0; the format is frozen (1.x only adds).
+
+* `HotspotObject`: the shape fields (`x`, `y`, `width`, `height`, `radius`, `points`, `targetName`) are marked required in the specification, as the validators always treated them.
+* New section "Canonical and Authoring Formats" in `oqse.md`: the JSON file is the canonical form that applications store and exchange; authoring formats (OQSE Markdown for notes, tool-specific shorthands) are only inputs converted to it, and item IDs survive edits.
+* Aligned before 1.0: `math-input` has `correctAnswers` (a list, like `short-answer`) instead of `correctAnswer` + `alternativeAnswers`, and no `tolerance` (answers are compared as LaTeX; numbers are `numeric-input`); `match-complex` has `prompts` / `matches` (like `match-pairs`) instead of `leftItems` / `rightItems`. `checkAnswer` and the JSON Schemas follow.
+* The sub-specifications (`oqse-manifest.md`, `oqse-progress.md`, `oqse-header.md`) point to the changelog in `oqse.md`.
+
+## 1.0.0-rc.5
+
+OQSE 1.0: choices with IDs, answers by ID, `skills`, Answer Formats and `checkAnswer`, typed-answer comparison, timeline rules, feature detection, version rules (0.x drafts are refused) and the JSON Schemas at `https://cdn.jsdelivr.net/npm/@memizy/oqse@1/schemas/`. See the "Version 1.0" changelog in `oqse.md`.

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript SDK for the Open Quiz & Study Exchange ecosystem, published as @memizy/oqse.
 
-🚀 **[OQSE Web Validator](https://memizy.github.io/memizy/)** - Online tool for easy testing and debugging of OQSE JSON structures in the browser (source: [`docs/`](./docs/), published by GitHub Pages).
+🚀 **[OQSE Web Validator](https://memizy.github.io/memizy/)** - Online tool for easy testing and debugging of OQSE JSON structures in the browser (source: [`docs/`](https://github.com/memizy/memizy/blob/main/packages/oqse/docs/), published by GitHub Pages).
 
 This repository contains:
 - The human-readable specifications split into four standalone documents:
@@ -36,6 +36,8 @@ const { success, data, errors, warnings } = loadOQSEFile(JSON.parse(text));
 
 ## Schemas
 
+The stable way to validate are the functions (`loadOQSEFile`, `safeValidateOQSEFile`, …) and the JSON Schemas. The exported `*Schema` objects are Zod schemas: their `parse` / `safeParse` behaviour is covered by semver, their Zod-specific API (`.extend`, `.shape`, the Zod major version) is not – a 1.x release may move to a newer Zod (noted in the changelog).
+
 The auto-generated JSON Schemas are published with this repository and are available at the following URLs:
 
 - Core OQSE Schema: https://cdn.jsdelivr.net/npm/@memizy/oqse@1/schemas/oqse-v1.0.json

package/dist/checkAnswer.cjs

@@ -1 +1 @@
-const e=require("./answers.cjs");function t(t,p){if(!t||typeof t!=`object`)throw Error(`checkAnswer: missing item`);switch(t.type){case`mcq-single`:return p===t.correctId;case`mcq-multi`:{let e=i(p);return e!==null&&c(e,t.correctIds)}case`true-false`:return r(p)===t.correctAnswer;case`short-answer`:{let n=p;return typeof n==`string`&&t.correctAnswers.some(r=>e.textAnswerMatches(n,r,t))}case`numeric-input`:{let e=n(p);return e!==null&&Math.abs(e-t.correctAnswer)<=(t.tolerance??0)+1e-9}case`slider`:{let e=n(p);return e!==null&&Math.abs(e-t.correctAnswer)<=(t.tolerance??0)+1e-9}case`math-input`:{if(typeof p!=`string`)return!1;let e=l(p);return[t.correctAnswer,...t.alternativeAnswers??[]].some(t=>l(t)===e)}case`sort-items`:{let e=i(p);return e!==null&&e.length===t.correctOrder.length&&e.every((e,n)=>e===t.correctOrder[n])}case`match-pairs`:{let e=s(p);return!!e&&t.prompts.every(n=>e[n.id]===t.pairs[n.id])}case`match-complex`:{let e=a(p);if(!e)return!1;let n=new Set(t.connections.map(([e,t])=>o(e,t))),r=new Set(e.map(([e,t])=>o(e,t))),i=[...r].filter(e=>n.has(e)).length;return i===r.size&&i>=(t.minCorrect??n.size)}case`matrix`:{let e=a(p);return e?c(e.map(([e,t])=>o(e,t)),t.correctCells.map(([e,t])=>o(e,t))):!1}case`fill-in-blanks`:{let n=s(p);return n?Object.entries(t.blanks).every(([r,i])=>{let a=n[r];return typeof a==`string`&&i.some(n=>e.textAnswerMatches(a,n,t))}):!1}case`fill-in-select`:{let e=s(p);return!!e&&Object.entries(t.blanks).every(([t,n])=>e[t]===n.correctId)}case`categorize`:{let e=s(p);return!!e&&t.items.every(t=>e[t.id]===t.correctCategoryId)}case`timeline`:{let n=i(p);if(!n||n.length!==t.events.length||new Set(n).size!==n.length)return!1;let r=n.map(e=>t.events.find(t=>t.id===e));return r.every(e=>!!e)&&e.isTimelineOrderCorrect(r)}case`pin-on-image`:{let e=(Array.isArray(p)?p:[p]).map(d);if(e.length===0||e.some(e=>e===null))return!1;if(!t.multipleCorrect)return e.length===1&&t.hotspots.some(t=>f(e[0],t));let n=new Set;for(let r of e){let e=t.hotspots.findIndex(e=>f(r,e));if(e===-1)return!1;n.add(e)}return n.size>=(t.minCorrect??t.hotspots.length)}case`diagram-label`:{let n=s(p);return n?t.zones.every(r=>{let i=n[r.id];if(t.requireTyping){let n=t.labels.find(e=>e.id===r.correctLabelId);return!!n&&typeof i==`string`&&e.textAnswerMatches(i,n.text,t)}return i===r.correctLabelId}):!1}case`pin-on-model`:{let e=(Array.isArray(p)?p:[p]).filter(e=>typeof e==`string`);if(e.length===0)return!1;let n=e=>t.hotspots.findIndex(t=>e.toLowerCase().includes(t.targetName.toLowerCase()));if(!t.multipleCorrect)return e.length===1&&n(e[0])!==-1;let r=new Set;for(let t of e){let e=n(t);if(e===-1)return!1;r.add(e)}return r.size>=(t.minCorrect??t.hotspots.length)}case`chess-puzzle`:{if(!Array.isArray(p)||p.some(e=>typeof e!=`string`))return!1;let e=p.map(u);return t.correctAnswers.some(t=>t.length===e.length&&t.every((t,n)=>u(t)===e[n]))}case`flashcard`:{let e=n(p);return e===3||e===4}case`note`:case`open-ended`:throw Error(`checkAnswer: "${t.type}" items cannot be checked automatically.`);default:throw Error(`checkAnswer: unsupported item type "${t.type}".`)}}function n(e){if(typeof e==`number`)return Number.isFinite(e)?e:null;if(typeof e!=`string`)return null;let t=e.trim().replace(/\s+/g,``).replace(`,`,`.`);return/^[-+]?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(t)?Number(t):null}function r(e){return typeof e==`boolean`?e:e===`true`||e!==`false`&&null}function i(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)?e:null}function a(e){return Array.isArray(e)&&e.every(e=>Array.isArray(e)&&e.length===2&&typeof e[0]==`string`&&typeof e[1]==`string`)?e:null}var o=(e,t)=>`${e}\u0000${t}`;function s(e){return e&&typeof e==`object`&&!Array.isArray(e)?e:null}function c(e,t){let n=new Set(e),r=new Set(t);return n.size===e.length&&n.size===r.size&&[...n].every(e=>r.has(e))}function l(e){return e.trim().replace(/^\$\$?|\$\$?$/g,``).replace(/\s+/g,``)}function u(e){return e.trim().replace(/[+#!?]+$/g,``).replace(/^0-0(-0)?$/,e=>e.replace(/0/g,`O`)).replace(/^([a-h](?:x[a-h])?[18])([QRBN])$/,`$1=$2`)}function d(e){let t=s(e);return t&&typeof t.x==`number`&&typeof t.y==`number`?{x:t.x,y:t.y}:null}function f(e,t){switch(t.type){case`rect`:return e.x>=t.x&&e.x<=t.x+t.width&&e.y>=t.y&&e.y<=t.y+t.height;case`circle`:return(e.x-t.x)**2+(e.y-t.y)**2<=t.radius**2;case`polygon`:{let n=!1,r=t.points;for(let t=0,i=r.length-1;t<r.length;i=t++)r[t].y>e.y!=r[i].y>e.y&&e.x<(r[i].x-r[t].x)*(e.y-r[t].y)/(r[i].y-r[t].y)+r[t].x&&(n=!n);return n}}}exports.checkAnswer=t;
+const e=require("./answers.cjs"),t=require("./mustUnderstand.cjs");function n(n,m){if(!n||typeof n!=`object`)throw Error(`checkAnswer: missing item`);let h=t.missingMustUnderstand(n);if(h.length>0)throw Error(`checkAnswer: the item needs properties this version cannot check (${h.join(`, `)}).`);switch(n.type){case`mcq-single`:return m===n.correctId;case`mcq-multi`:{let e=a(m);return e!==null&&l(e,n.correctIds)}case`true-false`:return i(m)===n.correctAnswer;case`short-answer`:{let t=m;return typeof t==`string`&&n.correctAnswers.some(r=>e.textAnswerMatches(t,r,n))}case`numeric-input`:{let e=r(m);return e!==null&&Math.abs(e-n.correctAnswer)<=(n.tolerance??0)+1e-9}case`slider`:{let e=r(m);return e!==null&&Math.abs(e-n.correctAnswer)<=(n.tolerance??0)+1e-9}case`math-input`:{if(typeof m!=`string`)return!1;let e=u(m);return n.correctAnswers.some(t=>u(t)===e)}case`sort-items`:{let e=a(m);return e!==null&&e.length===n.correctOrder.length&&e.every((e,t)=>e===n.correctOrder[t])}case`match-pairs`:{let e=c(m);return!!e&&n.prompts.every(t=>e[t.id]===n.pairs[t.id])}case`match-complex`:{let e=o(m);if(!e)return!1;let t=new Set(n.connections.map(([e,t])=>s(e,t))),r=new Set(e.map(([e,t])=>s(e,t))),i=[...r].filter(e=>t.has(e)).length;return i===r.size&&i>=(n.minCorrect??t.size)}case`matrix`:{let e=o(m);return e?l(e.map(([e,t])=>s(e,t)),n.correctCells.map(([e,t])=>s(e,t))):!1}case`fill-in-blanks`:{let t=c(m);return t?Object.entries(n.blanks).every(([r,i])=>{let a=t[r];return typeof a==`string`&&i.some(t=>e.textAnswerMatches(a,t,n))}):!1}case`fill-in-select`:{let e=c(m);return!!e&&Object.entries(n.blanks).every(([t,n])=>e[t]===n.correctId)}case`categorize`:{let e=c(m);return!!e&&n.items.every(t=>e[t.id]===t.correctCategoryId)}case`timeline`:{let t=a(m);if(!t||t.length!==n.events.length||new Set(t).size!==t.length)return!1;let r=t.map(e=>n.events.find(t=>t.id===e));return r.every(e=>!!e)&&e.isTimelineOrderCorrect(r)}case`pin-on-image`:{let e=(Array.isArray(m)?m:[m]).map(f);if(e.length===0||e.some(e=>e===null))return!1;if(!n.multipleCorrect)return e.length===1&&n.hotspots.some(t=>p(e[0],t));let t=new Set;for(let r of e){let e=n.hotspots.findIndex(e=>p(r,e));if(e===-1)return!1;t.add(e)}return t.size>=(n.minCorrect??n.hotspots.length)}case`diagram-label`:{let t=c(m);return t?n.zones.every(r=>{let i=t[r.id];if(n.requireTyping){let t=n.labels.find(e=>e.id===r.correctLabelId);return!!t&&typeof i==`string`&&e.textAnswerMatches(i,t.text,n)}return i===r.correctLabelId}):!1}case`pin-on-model`:{let e=(Array.isArray(m)?m:[m]).filter(e=>typeof e==`string`);if(e.length===0)return!1;let t=e=>n.hotspots.findIndex(t=>e.toLowerCase().includes(t.targetName.toLowerCase()));if(!n.multipleCorrect)return e.length===1&&t(e[0])!==-1;let r=new Set;for(let n of e){let e=t(n);if(e===-1)return!1;r.add(e)}return r.size>=(n.minCorrect??n.hotspots.length)}case`chess-puzzle`:{if(!Array.isArray(m)||m.some(e=>typeof e!=`string`))return!1;let e=m.map(d);return n.correctAnswers.some(t=>t.length===e.length&&t.every((t,n)=>d(t)===e[n]))}case`flashcard`:{let e=r(m);return e===3||e===4}case`note`:case`open-ended`:throw Error(`checkAnswer: "${n.type}" items cannot be checked automatically.`);default:throw Error(`checkAnswer: unsupported item type "${n.type}".`)}}function r(e){if(typeof e==`number`)return Number.isFinite(e)?e:null;if(typeof e!=`string`)return null;let t=e.trim().replace(/\s+/g,``).replace(`,`,`.`);return/^[-+]?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(t)?Number(t):null}function i(e){return typeof e==`boolean`?e:e===`true`||e!==`false`&&null}function a(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)?e:null}function o(e){return Array.isArray(e)&&e.every(e=>Array.isArray(e)&&e.length===2&&typeof e[0]==`string`&&typeof e[1]==`string`)?e:null}var s=(e,t)=>`${e}\u0000${t}`;function c(e){return e&&typeof e==`object`&&!Array.isArray(e)?e:null}function l(e,t){let n=new Set(e),r=new Set(t);return n.size===e.length&&n.size===r.size&&[...n].every(e=>r.has(e))}function u(e){return e.trim().replace(/^\$\$?|\$\$?$/g,``).replace(/\s+/g,``)}function d(e){return e.trim().replace(/[+#!?]+$/g,``).replace(/^0-0(-0)?$/,e=>e.replace(/0/g,`O`)).replace(/^([a-h](?:x[a-h])?[18])([QRBN])$/,`$1=$2`)}function f(e){let t=c(e);return t&&typeof t.x==`number`&&typeof t.y==`number`?{x:t.x,y:t.y}:null}function p(e,t){switch(t.type){case`rect`:return e.x>=t.x&&e.x<=t.x+t.width&&e.y>=t.y&&e.y<=t.y+t.height;case`circle`:return(e.x-t.x)**2+(e.y-t.y)**2<=t.radius**2;case`polygon`:{let n=!1,r=t.points;for(let t=0,i=r.length-1;t<r.length;i=t++)r[t].y>e.y!=r[i].y>e.y&&e.x<(r[i].x-r[t].x)*(e.y-r[t].y)/(r[i].y-r[t].y)+r[t].x&&(n=!n);return n}}}exports.checkAnswer=n;

package/dist/checkAnswer.js

@@ -1,157 +1,160 @@
 import { isTimelineOrderCorrect as e, textAnswerMatches as t } from "./answers.js";
+import { missingMustUnderstand as n } from "./mustUnderstand.js";
 //#region src/checkAnswer.ts
-function n(n, m) {
-	if (!n || typeof n != "object") throw Error("checkAnswer: missing item");
-	switch (n.type) {
-		case "mcq-single": return m === n.correctId;
+function r(r, h) {
+	if (!r || typeof r != "object") throw Error("checkAnswer: missing item");
+	let g = n(r);
+	if (g.length > 0) throw Error(`checkAnswer: the item needs properties this version cannot check (${g.join(", ")}).`);
+	switch (r.type) {
+		case "mcq-single": return h === r.correctId;
 		case "mcq-multi": {
-			let e = a(m);
-			return e !== null && l(e, n.correctIds);
+			let e = o(h);
+			return e !== null && u(e, r.correctIds);
 		}
-		case "true-false": return i(m) === n.correctAnswer;
+		case "true-false": return a(h) === r.correctAnswer;
 		case "short-answer": {
-			let e = m;
-			return typeof e == "string" && n.correctAnswers.some((r) => t(e, r, n));
+			let e = h;
+			return typeof e == "string" && r.correctAnswers.some((n) => t(e, n, r));
 		}
 		case "numeric-input": {
-			let e = r(m);
-			return e !== null && Math.abs(e - n.correctAnswer) <= (n.tolerance ?? 0) + 1e-9;
+			let e = i(h);
+			return e !== null && Math.abs(e - r.correctAnswer) <= (r.tolerance ?? 0) + 1e-9;
 		}
 		case "slider": {
-			let e = r(m);
-			return e !== null && Math.abs(e - n.correctAnswer) <= (n.tolerance ?? 0) + 1e-9;
+			let e = i(h);
+			return e !== null && Math.abs(e - r.correctAnswer) <= (r.tolerance ?? 0) + 1e-9;
 		}
 		case "math-input": {
-			if (typeof m != "string") return !1;
-			let e = u(m);
-			return [n.correctAnswer, ...n.alternativeAnswers ?? []].some((t) => u(t) === e);
+			if (typeof h != "string") return !1;
+			let e = d(h);
+			return r.correctAnswers.some((t) => d(t) === e);
 		}
 		case "sort-items": {
-			let e = a(m);
-			return e !== null && e.length === n.correctOrder.length && e.every((e, t) => e === n.correctOrder[t]);
+			let e = o(h);
+			return e !== null && e.length === r.correctOrder.length && e.every((e, t) => e === r.correctOrder[t]);
 		}
 		case "match-pairs": {
-			let e = c(m);
-			return !!e && n.prompts.every((t) => e[t.id] === n.pairs[t.id]);
+			let e = l(h);
+			return !!e && r.prompts.every((t) => e[t.id] === r.pairs[t.id]);
 		}
 		case "match-complex": {
-			let e = o(m);
+			let e = s(h);
 			if (!e) return !1;
-			let t = new Set(n.connections.map(([e, t]) => s(e, t))), r = new Set(e.map(([e, t]) => s(e, t))), i = [...r].filter((e) => t.has(e)).length;
-			return i === r.size && i >= (n.minCorrect ?? t.size);
+			let t = new Set(r.connections.map(([e, t]) => c(e, t))), n = new Set(e.map(([e, t]) => c(e, t))), i = [...n].filter((e) => t.has(e)).length;
+			return i === n.size && i >= (r.minCorrect ?? t.size);
 		}
 		case "matrix": {
-			let e = o(m);
-			return e ? l(e.map(([e, t]) => s(e, t)), n.correctCells.map(([e, t]) => s(e, t))) : !1;
+			let e = s(h);
+			return e ? u(e.map(([e, t]) => c(e, t)), r.correctCells.map(([e, t]) => c(e, t))) : !1;
 		}
 		case "fill-in-blanks": {
-			let e = c(m);
-			return e ? Object.entries(n.blanks).every(([r, i]) => {
-				let a = e[r];
-				return typeof a == "string" && i.some((e) => t(a, e, n));
+			let e = l(h);
+			return e ? Object.entries(r.blanks).every(([n, i]) => {
+				let a = e[n];
+				return typeof a == "string" && i.some((e) => t(a, e, r));
 			}) : !1;
 		}
 		case "fill-in-select": {
-			let e = c(m);
-			return !!e && Object.entries(n.blanks).every(([t, n]) => e[t] === n.correctId);
+			let e = l(h);
+			return !!e && Object.entries(r.blanks).every(([t, n]) => e[t] === n.correctId);
 		}
 		case "categorize": {
-			let e = c(m);
-			return !!e && n.items.every((t) => e[t.id] === t.correctCategoryId);
+			let e = l(h);
+			return !!e && r.items.every((t) => e[t.id] === t.correctCategoryId);
 		}
 		case "timeline": {
-			let t = a(m);
-			if (!t || t.length !== n.events.length || new Set(t).size !== t.length) return !1;
-			let r = t.map((e) => n.events.find((t) => t.id === e));
-			return r.every((e) => !!e) && e(r);
+			let t = o(h);
+			if (!t || t.length !== r.events.length || new Set(t).size !== t.length) return !1;
+			let n = t.map((e) => r.events.find((t) => t.id === e));
+			return n.every((e) => !!e) && e(n);
 		}
 		case "pin-on-image": {
-			let e = (Array.isArray(m) ? m : [m]).map(f);
+			let e = (Array.isArray(h) ? h : [h]).map(p);
 			if (e.length === 0 || e.some((e) => e === null)) return !1;
-			if (!n.multipleCorrect) return e.length === 1 && n.hotspots.some((t) => p(e[0], t));
+			if (!r.multipleCorrect) return e.length === 1 && r.hotspots.some((t) => m(e[0], t));
 			let t = /* @__PURE__ */ new Set();
-			for (let r of e) {
-				let e = n.hotspots.findIndex((e) => p(r, e));
+			for (let n of e) {
+				let e = r.hotspots.findIndex((e) => m(n, e));
 				if (e === -1) return !1;
 				t.add(e);
 			}
-			return t.size >= (n.minCorrect ?? n.hotspots.length);
+			return t.size >= (r.minCorrect ?? r.hotspots.length);
 		}
 		case "diagram-label": {
-			let e = c(m);
-			return e ? n.zones.every((r) => {
-				let i = e[r.id];
-				if (n.requireTyping) {
-					let e = n.labels.find((e) => e.id === r.correctLabelId);
-					return !!e && typeof i == "string" && t(i, e.text, n);
+			let e = l(h);
+			return e ? r.zones.every((n) => {
+				let i = e[n.id];
+				if (r.requireTyping) {
+					let e = r.labels.find((e) => e.id === n.correctLabelId);
+					return !!e && typeof i == "string" && t(i, e.text, r);
 				}
-				return i === r.correctLabelId;
+				return i === n.correctLabelId;
 			}) : !1;
 		}
 		case "pin-on-model": {
-			let e = (Array.isArray(m) ? m : [m]).filter((e) => typeof e == "string");
+			let e = (Array.isArray(h) ? h : [h]).filter((e) => typeof e == "string");
 			if (e.length === 0) return !1;
-			let t = (e) => n.hotspots.findIndex((t) => e.toLowerCase().includes(t.targetName.toLowerCase()));
-			if (!n.multipleCorrect) return e.length === 1 && t(e[0]) !== -1;
-			let r = /* @__PURE__ */ new Set();
-			for (let n of e) {
-				let e = t(n);
+			let t = (e) => r.hotspots.findIndex((t) => e.toLowerCase().includes(t.targetName.toLowerCase()));
+			if (!r.multipleCorrect) return e.length === 1 && t(e[0]) !== -1;
+			let n = /* @__PURE__ */ new Set();
+			for (let r of e) {
+				let e = t(r);
 				if (e === -1) return !1;
-				r.add(e);
+				n.add(e);
 			}
-			return r.size >= (n.minCorrect ?? n.hotspots.length);
+			return n.size >= (r.minCorrect ?? r.hotspots.length);
 		}
 		case "chess-puzzle": {
-			if (!Array.isArray(m) || m.some((e) => typeof e != "string")) return !1;
-			let e = m.map(d);
-			return n.correctAnswers.some((t) => t.length === e.length && t.every((t, n) => d(t) === e[n]));
+			if (!Array.isArray(h) || h.some((e) => typeof e != "string")) return !1;
+			let e = h.map(f);
+			return r.correctAnswers.some((t) => t.length === e.length && t.every((t, n) => f(t) === e[n]));
 		}
 		case "flashcard": {
-			let e = r(m);
+			let e = i(h);
 			return e === 3 || e === 4;
 		}
 		case "note":
-		case "open-ended": throw Error(`checkAnswer: "${n.type}" items cannot be checked automatically.`);
-		default: throw Error(`checkAnswer: unsupported item type "${n.type}".`);
+		case "open-ended": throw Error(`checkAnswer: "${r.type}" items cannot be checked automatically.`);
+		default: throw Error(`checkAnswer: unsupported item type "${r.type}".`);
 	}
 }
-function r(e) {
+function i(e) {
 	if (typeof e == "number") return Number.isFinite(e) ? e : null;
 	if (typeof e != "string") return null;
 	let t = e.trim().replace(/\s+/g, "").replace(",", ".");
 	return /^[-+]?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(t) ? Number(t) : null;
 }
-function i(e) {
+function a(e) {
 	return typeof e == "boolean" ? e : e === "true" || e !== "false" && null;
 }
-function a(e) {
+function o(e) {
 	return Array.isArray(e) && e.every((e) => typeof e == "string") ? e : null;
 }
-function o(e) {
+function s(e) {
 	return Array.isArray(e) && e.every((e) => Array.isArray(e) && e.length === 2 && typeof e[0] == "string" && typeof e[1] == "string") ? e : null;
 }
-var s = (e, t) => `${e}\u0000${t}`;
-function c(e) {
+var c = (e, t) => `${e}\u0000${t}`;
+function l(e) {
 	return e && typeof e == "object" && !Array.isArray(e) ? e : null;
 }
-function l(e, t) {
+function u(e, t) {
 	let n = new Set(e), r = new Set(t);
 	return n.size === e.length && n.size === r.size && [...n].every((e) => r.has(e));
 }
-function u(e) {
+function d(e) {
 	return e.trim().replace(/^\$\$?|\$\$?$/g, "").replace(/\s+/g, "");
 }
-function d(e) {
+function f(e) {
 	return e.trim().replace(/[+#!?]+$/g, "").replace(/^0-0(-0)?$/, (e) => e.replace(/0/g, "O")).replace(/^([a-h](?:x[a-h])?[18])([QRBN])$/, "$1=$2");
 }
-function f(e) {
-	let t = c(e);
+function p(e) {
+	let t = l(e);
 	return t && typeof t.x == "number" && typeof t.y == "number" ? {
 		x: t.x,
 		y: t.y
 	} : null;
 }
-function p(e, t) {
+function m(e, t) {
 	switch (t.type) {
 		case "rect": return e.x >= t.x && e.x <= t.x + t.width && e.y >= t.y && e.y <= t.y + t.height;
 		case "circle": return (e.x - t.x) ** 2 + (e.y - t.y) ** 2 <= t.radius ** 2;
@@ -163,4 +166,4 @@ function p(e, t) {
 	}
 }
 //#endregion
-export { n as checkAnswer };
+export { r as checkAnswer };

package/dist/compatibility.cjs

@@ -1 +1 @@
-const e=require("./manifest.cjs"),t=require("./features.cjs");function n(n,r){let i=e.withManifestDefaults(r).capabilities,a=(e,t)=>!!e&&e.length>0&&(e.includes(`*`)||e.includes(t)),o=[...new Set(n.items.map(e=>e.type))].filter(e=>!a(i.types,e)),s=[],c=[],l=(e,t)=>{for(let[n,r]of Object.entries(e??{})){let e=i.assets?.[r.type],a={path:`${t}.${n}`,type:r.type,mimeType:r.mimeType};if(!e||e.length===0)s.push(a);else if(e.includes(`*`))continue;else r.mimeType?e.includes(r.mimeType)||s.push(a):c.push(a)}};l(n.meta.assets,`meta.assets`),n.items.forEach((e,t)=>l(e.assets,`items[${t}].assets`));let u=n.meta.requirements,d=(e,t)=>(e??[]).filter(e=>!(t??[]).includes(e)),f=d(t.effectiveFeatures(n),i.features),p=d(u?.latexPackages,i.latexPackages),m=[...d(u?.itemProperties,i.itemProperties),...d(u?.metaProperties,i.metaProperties)],h=e.isVersionCompatible(n.version,r),g=h&&o.length===0&&s.length===0;return{level:g?f.length>0||p.length>0?`simplified`:`full`:`incompatible`,compatible:g,versionCompatible:h,unsupportedTypes:o,unsupportedAssets:s,unverifiedAssets:c,missingFeatures:f,missingLatexPackages:p,missingProperties:m}}exports.checkCompatibility=n;
+const e=require("./oqse.cjs"),t=require("./manifest.cjs"),n=require("./features.cjs");function r(r,i){let a=t.withManifestDefaults(i).capabilities,o=(e,t)=>!!e&&e.length>0&&(e.includes(`*`)||e.includes(t)),s=[...new Set(r.items.map(e=>e.type))].filter(e=>!o(a.types,e)),c=[],l=[],u=(t,n)=>{for(let[r,i]of Object.entries(t??{})){if(!e.MEDIA_TYPES.includes(i.type))continue;let t=a.assets?.[i.type],o={path:`${n}.${r}`,type:i.type,mimeType:i.mimeType};if(!t||t.length===0)c.push(o);else if(t.includes(`*`))continue;else i.mimeType?t.includes(i.mimeType)||c.push(o):l.push(o)}};u(r.meta.assets,`meta.assets`),r.items.forEach((e,t)=>u(e.assets,`items[${t}].assets`));let d=r.meta.requirements,f=(e,t)=>(e??[]).filter(e=>!(t??[]).includes(e)),p=f(n.effectiveFeatures(r),a.features),m=f(d?.latexPackages,a.latexPackages),h=[...f(d?.itemProperties,a.itemProperties),...f(d?.metaProperties,a.metaProperties)],g=t.isVersionCompatible(r.version,i),_=g&&s.length===0&&c.length===0;return{level:_?p.length>0||m.length>0?`simplified`:`full`:`incompatible`,compatible:_,versionCompatible:g,unsupportedTypes:s,unsupportedAssets:c,unverifiedAssets:l,missingFeatures:p,missingLatexPackages:m,missingProperties:h}}exports.checkCompatibility=r;

package/dist/compatibility.js

@@ -1,32 +1,34 @@
-import { isVersionCompatible as e, withManifestDefaults as t } from "./manifest.js";
-import { effectiveFeatures as n } from "./features.js";
+import { MEDIA_TYPES as e } from "./oqse.js";
+import { isVersionCompatible as t, withManifestDefaults as n } from "./manifest.js";
+import { effectiveFeatures as r } from "./features.js";
 //#region src/compatibility.ts
-function r(r, i) {
-	let a = t(i).capabilities, o = (e, t) => !!e && e.length > 0 && (e.includes("*") || e.includes(t)), s = [...new Set(r.items.map((e) => e.type))].filter((e) => !o(a.types, e)), c = [], l = [], u = (e, t) => {
-		for (let [n, r] of Object.entries(e ?? {})) {
-			let e = a.assets?.[r.type], i = {
-				path: `${t}.${n}`,
-				type: r.type,
-				mimeType: r.mimeType
+function i(i, a) {
+	let o = n(a).capabilities, s = (e, t) => !!e && e.length > 0 && (e.includes("*") || e.includes(t)), c = [...new Set(i.items.map((e) => e.type))].filter((e) => !s(o.types, e)), l = [], u = [], d = (t, n) => {
+		for (let [r, i] of Object.entries(t ?? {})) {
+			if (!e.includes(i.type)) continue;
+			let t = o.assets?.[i.type], a = {
+				path: `${n}.${r}`,
+				type: i.type,
+				mimeType: i.mimeType
 			};
-			if (!e || e.length === 0) c.push(i);
-			else if (e.includes("*")) continue;
-			else r.mimeType ? e.includes(r.mimeType) || c.push(i) : l.push(i);
+			if (!t || t.length === 0) l.push(a);
+			else if (t.includes("*")) continue;
+			else i.mimeType ? t.includes(i.mimeType) || l.push(a) : u.push(a);
 		}
 	};
-	u(r.meta.assets, "meta.assets"), r.items.forEach((e, t) => u(e.assets, `items[${t}].assets`));
-	let d = r.meta.requirements, f = (e, t) => (e ?? []).filter((e) => !(t ?? []).includes(e)), p = f(n(r), a.features), m = f(d?.latexPackages, a.latexPackages), h = [...f(d?.itemProperties, a.itemProperties), ...f(d?.metaProperties, a.metaProperties)], g = e(r.version, i), _ = g && s.length === 0 && c.length === 0;
+	d(i.meta.assets, "meta.assets"), i.items.forEach((e, t) => d(e.assets, `items[${t}].assets`));
+	let f = i.meta.requirements, p = (e, t) => (e ?? []).filter((e) => !(t ?? []).includes(e)), m = p(r(i), o.features), h = p(f?.latexPackages, o.latexPackages), g = [...p(f?.itemProperties, o.itemProperties), ...p(f?.metaProperties, o.metaProperties)], _ = t(i.version, a), v = _ && c.length === 0 && l.length === 0;
 	return {
-		level: _ ? p.length > 0 || m.length > 0 ? "simplified" : "full" : "incompatible",
-		compatible: _,
-		versionCompatible: g,
-		unsupportedTypes: s,
-		unsupportedAssets: c,
-		unverifiedAssets: l,
-		missingFeatures: p,
-		missingLatexPackages: m,
-		missingProperties: h
+		level: v ? m.length > 0 || h.length > 0 ? "simplified" : "full" : "incompatible",
+		compatible: v,
+		versionCompatible: _,
+		unsupportedTypes: c,
+		unsupportedAssets: l,
+		unverifiedAssets: u,
+		missingFeatures: m,
+		missingLatexPackages: h,
+		missingProperties: g
 	};
 }
 //#endregion
-export { r as checkCompatibility };
+export { i as checkCompatibility };

package/dist/fileValidation.cjs

@@ -1,2 +1,2 @@
-const e=require("./oqse.cjs"),t=require("./utils.cjs"),n=require("./oqseValidation.cjs"),r=require("./manifest.cjs"),i=require("./markdownUtils.cjs"),a=require("./richTextProcessor.cjs"),o=require("./assets.cjs"),s=require("./richTextFields.cjs"),c=require("./features.cjs");var l=class extends Error{errors;warnings;constructor(e,t){super(`Invalid OQSE file:\n${u(e).join(`
-`)}`),this.name=`OQSEValidationError`,this.errors=e,this.warnings=t}};function u(e){return e.map(e=>e.path?`${e.path}: ${e.message}`:e.message)}var d=1,f=`1.0`;function p(e){return v(e,`load`)}function m(e){let t=v(e,`strict`),n=t.success&&t.errors.length===0;return{success:n,data:n?t.data:void 0,errors:t.errors,warnings:t.warnings}}function h(e){let t=m(e);if(!t.success)throw new l(t.errors,t.warnings);return t.data}var g=new Set(e.OFFICIAL_ITEM_TYPES),_=class{errors=[];warnings=[];add(e,n,r,i,a){let o={severity:e,code:n,message:r,path:t.formatPath(i)};a&&(o.itemId=a),(e===`error`?this.errors:this.warnings).push(o)}addZod(e,t,n,r){for(let i of e.issues)this.add(`error`,t,i.message,[...n,...i.path],r)}};function v(e,i){let o=new _,l=()=>({success:!1,errors:o.errors,warnings:o.warnings}),u=i===`strict`?`error`:`warning`;try{t.validateJsonDepth(e,10)}catch(e){return o.add(`error`,`SECURITY_LIMIT`,e.message,[]),l()}if(!w(e)||!w(e.meta)||!Array.isArray(e.items))return o.add(`error`,`INVALID_ROOT`,`An OQSE file must be an object with "version", "meta" and "items" (array).`,[]),l();let d=structuredClone(e);if(d.$schema!==void 0&&typeof d.$schema!=`string`)return o.add(`error`,`INVALID_ROOT`,`"$schema" must be a string URL.`,[`$schema`]),l();if(typeof d.version!=`string`||!/^\d+\.\d+$/.test(d.version))return o.add(`error`,`INVALID_VERSION`,`Version must be in MAJOR.MINOR format (e.g. "1.0").`,[`version`]),l();let f=Number(d.version.split(`.`)[0]);if(f===0)return o.add(`error`,`UNSUPPORTED_VERSION`,`OQSE ${d.version} is a pre-release version; this library reads OQSE 1.x (convert the set to 1.0).`,[`version`]),l();if(f!==1&&o.add(`warning`,`UNSUPPORTED_VERSION`,`Unsupported MAJOR version ${d.version}; loading in best-effort mode.`,[`version`]),d.items.length>1e4)return o.add(`error`,`TOO_MANY_ITEMS`,`Maximum 10000 items per set.`,[`items`]),l();if(i===`load`&&!C(d.meta,[`meta`,`assets`],o))return l();let p=n.OQSEMetaSchema.safeParse(d.meta);if(!p.success)return o.addZod(p.error,`INVALID_META`,[`meta`]),l();let m=p.data,h={features:r.OFFICIAL_FEATURE_KEYS,itemProperties:r.OFFICIAL_ITEM_PROPERTIES,metaProperties:r.OFFICIAL_META_PROPERTIES};for(let[e,t]of Object.entries(h))for(let n of m.requirements?.[e]??[])!n.startsWith(`x-`)&&!t.includes(n)&&o.add(`warning`,`UNKNOWN_FEATURE`,`Unknown ${e===`features`?`feature`:`property`} "${n}" in requirements.${e} (ignored).`,[`meta`,`requirements`,e]);let v=new Set(m.requirements?.features??[]),x=v.has(`html`),S=v.has(`latex`);b(m.assets,[`meta`,`assets`],o,i),m.thumbnail&&!m.assets?.[m.thumbnail]&&(o.add(u,`MISSING_THUMBNAIL_ASSET`,`Thumbnail references non-existent asset "${m.thumbnail}".`,[`meta`,`thumbnail`]),i===`load`&&delete m.thumbnail);for(let[e,t]of s.metaRichText(m)){let n=x?null:a.findRawHtml(t,{latex:S});n&&(o.add(u,`RAW_HTML_NOT_ALLOWED`,T(n),e),i===`load`&&E(m,e.slice(1)))}let D=new Set([m.id]),O=[];d.items.forEach((e,t)=>{let r=[`items`,t],a=w(e)&&typeof e.id==`string`?e.id:void 0,s=w(e)?e.type:void 0;if(typeof s==`string`&&!s.startsWith(`x-`)&&!g.has(s)){o.add(u,`UNKNOWN_ITEM_TYPE`,`Unknown item type "${s}" (custom types must use the "x-" prefix).`,[...r,`type`],a);return}if(i===`load`&&w(e)&&!C(e,[...r,`assets`],o,a))return;let c=n.getItemSchema(e).safeParse(e);if(!c.success){o.addZod(c.error,`INVALID_ITEM`,r,a);return}let l=c.data;if(D.has(l.id)){o.add(`error`,`DUPLICATE_ID`,`Duplicate ID "${l.id}" (IDs must be unique within the set, including meta.id).`,[...r,`id`],l.id);return}D.add(l.id),b(l.assets,[...r,`assets`],o,i,l.id),y(l,r,m,x,S,o,u)&&O.push({item:l,index:t})});let k=O.map(e=>e.item),A=new Set(k.map(e=>e.id)),j=new Set((m.sourceMaterials??[]).map(e=>e.id));for(let{item:e,index:t}of O){let n=[`items`,t];for(let t of[`relatedItems`,`dependencyItems`]){let r=e[t];if(!r)continue;let a=r.filter(t=>t!==e.id&&A.has(t));a.length!==r.length&&(o.add(u,`DANGLING_REFERENCE`,`${t} contains IDs that do not exist in the set or reference the item itself.`,[...n,t],e.id),i===`load`&&(e[t]=a))}if(e.sources){let t=e.sources.filter(e=>j.has(e.id));t.length!==e.sources.length&&(o.add(u,`DANGLING_REFERENCE`,`sources reference source materials that do not exist in meta.sourceMaterials.`,[...n,`sources`],e.id),i===`load`&&(e.sources=t))}}for(let e of c.detectFeatures({meta:m,items:k}))e!==`html`&&!v.has(e)&&o.add(`warning`,`UNDECLARED_FEATURE`,`The content uses "${e}", but meta.requirements.features does not declare it.`,[`meta`,`requirements`,`features`]);if(!S)for(let{item:e,index:t}of O){let n=s.itemRichText(e).find(([,e])=>c.looksLikeLatex(e));n&&o.add(`warning`,`LOOKS_LIKE_LATEX`,`The text looks like a LaTeX formula; if it is one, declare the "latex" feature (otherwise $ is an ordinary character).`,[`items`,t,...n[0]],e.id)}return{success:!0,data:{...d,meta:m,items:k},errors:o.errors,warnings:o.warnings}}function y(e,t,n,r,c,l,u){let d=!0;if(!r)for(let[n,r]of s.itemRichText(e)){let i=a.findRawHtml(r,{latex:c});i&&(l.add(`error`,`RAW_HTML_NOT_ALLOWED`,T(i),[...t,...n],e.id),d=!1)}if(`targetAsset`in e&&typeof e.targetAsset==`string`&&!e.type.startsWith(`x-`)){let r=o.resolveAsset(e.targetAsset,e,n),i=e.type===`pin-on-model`?`model`:`image`;r?r.type!==i&&(l.add(`error`,`INVALID_TARGET_ASSET`,`targetAsset "${e.targetAsset}" must be of type "${i}".`,[...t,`targetAsset`],e.id),d=!1):(l.add(`error`,`MISSING_TARGET_ASSET`,`targetAsset "${e.targetAsset}" does not exist in item.assets or meta.assets.`,[...t,`targetAsset`],e.id),d=!1)}let f=e.type===`timeline`?e.events:e.type===`categorize`?e.items:void 0;if(f){let n=f.map(e=>e.id);new Set(n).size!==n.length&&(l.add(`error`,`DUPLICATE_ID`,`Internal IDs must be unique within the item.`,[...t,e.type===`timeline`?`events`:`items`],e.id),d=!1)}if(e.type===`chess-puzzle`&&e.correctAnswers.some(e=>e.length%2==0)&&l.add(`warning`,`CHESS_SEQUENCE_LENGTH`,`Each move sequence should end with the learner's move (an odd number of moves; the application plays the replies).`,[...t,`correctAnswers`],e.id),e.type===`note`)for(let n of[`content`,`hiddenContent`]){let r=e[n];r&&i.findHeadings(i.splitLines(r)).some(e=>e.level===1)&&l.add(`warning`,`NOTE_HEADING_LEVEL`,`Headings inside a note should start at level 2 (##); the note title is level 1.`,[...t,n],e.id)}let p=e.type===`fill-in-blanks`||e.type===`fill-in-select`;for(let[n,r]of s.itemRichText(e)){for(let i of x(r)){if(/^https:\/\//i.test(i))continue;let r=/^http:\/\//i.test(i);l.add(r?`warning`:u,`INVALID_IMAGE_URL`,r?`Image "${i}" uses http:// (prefer https://).`:`Image "${i}" needs an absolute https:// URL (use <asset:key /> for other media).`,[...t,...n],e.id)}!(p&&n.length===1&&n[0]===`text`)&&/<blank:[a-zA-Z0-9_-]+\s*\/>/i.test(r)&&l.add(`warning`,`BLANK_OUTSIDE_TEXT`,`Blank tags belong only in the text of fill-in-blanks and fill-in-select (shown here as an empty line).`,[...t,...n],e.id)}for(let[r,i]of s.itemRichText(e))for(let s of a.findAssetKeys(i))o.resolveAsset(s,e,n)||l.add(`warning`,`MISSING_ASSET`,`<asset:${s} /> does not exist in item.assets or meta.assets.`,[...t,...r],e.id);for(let r of Object.keys(e.assets??{}))n.assets?.[r]&&l.add(`warning`,`ASSET_SHADOWED`,`Item asset "${r}" shadows a global asset with the same key; use unique keys.`,[...t,`assets`,r],e.id);return d}function b(e,t,n,r,i){for(let[a,o]of Object.entries(e??{}))o.type!==`image`||o.altText?.trim()||(n.add(r===`strict`?`error`:`warning`,`MISSING_ALT_TEXT`,`Image "${a}" has no altText (alternative text for screen readers).`,[...t,a,`altText`],i),r===`load`&&(o.altText=S(o.value)||a))}function x(e){return[...e.replace(/^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![\s\S]))/gm,``).replace(/`[^`\n]+`/g,``).matchAll(/!\[[^\]\n]*\]\(\s*<?([^)\s>]+)/g)].map(e=>e[1])}function S(e){return(e.split(/[?#]/)[0].split(`/`).pop()??``).replace(/\.[a-z0-9]+$/i,``).replace(/[-_]+/g,` `).trim()}function C(e,t,n,r){let i=e.assets;if(!w(i))return!0;let a={};for(let[e,o]of Object.entries(i)){let i=e.toLowerCase();if(i in a)return n.add(`error`,`ASSET_KEY_COLLISION`,`Asset keys collide after lowercasing ("${e}").`,[...t,e],r),!1;i!==e&&n.add(`warning`,`ASSET_KEY_NORMALIZED`,`Asset key "${e}" was converted to "${i}".`,[...t,e],r),a[i]=o}e.assets=a;for(let t of[`thumbnail`,`targetAsset`])typeof e[t]==`string`&&(e[t]=e[t].toLowerCase());return!0}function w(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function T(e){return`Raw HTML ${e} is not allowed unless the set declares the "html" feature (use Markdown instead).`}function E(e,t){let n=e;for(let e of t.slice(0,-1))n=n[e];delete n[t[t.length-1]]}exports.OQSEValidationError=l,exports.OQSE_VERSION=f,exports.SUPPORTED_OQSE_MAJOR_VERSION=d,exports.formatOQSEIssues=u,exports.loadOQSEFile=p,exports.safeValidateOQSEFile=m,exports.validateOQSEFile=h;
+const e=require("./oqse.cjs"),t=require("./utils.cjs"),n=require("./oqseValidation.cjs"),r=require("./manifest.cjs"),i=require("./markdownUtils.cjs"),a=require("./richTextProcessor.cjs"),o=require("./mustUnderstand.cjs"),s=require("./assets.cjs"),c=require("./richTextFields.cjs"),l=require("./features.cjs");var u=class extends Error{errors;warnings;constructor(e,t){super(`Invalid OQSE file:\n${d(e).join(`
+`)}`),this.name=`OQSEValidationError`,this.errors=e,this.warnings=t}};function d(e){return e.map(e=>e.path?`${e.path}: ${e.message}`:e.message)}var f=1,p=`1.0`;function m(e,t={}){return b(e,`load`,t)}function h(e,t={}){let n=b(e,`strict`,t),r=n.success&&n.errors.length===0;return{success:r,data:r?n.data:void 0,unsupportedItems:n.unsupportedItems,errors:n.errors,warnings:n.warnings}}function g(e,t){let n=[...e.items];for(let{index:e,item:r}of[...t].sort((e,t)=>e.index-t.index))n.splice(Math.min(e,n.length),0,structuredClone(r));return{...e,items:n}}function _(e,t={}){let n=h(e,t);if(!n.success)throw new u(n.errors,n.warnings);return n.data}var v=new Set(e.OFFICIAL_ITEM_TYPES),y=class{errors=[];warnings=[];add(e,n,r,i,a){let o={severity:e,code:n,message:r,path:t.formatPath(i)};a&&(o.itemId=a),(e===`error`?this.errors:this.warnings).push(o)}addZod(e,t,n,r){for(let i of e.issues)this.add(`error`,t,i.message,[...n,...i.path],r)}};function b(e,i,s){let u=new y,d=[],f=()=>({success:!1,unsupportedItems:d,errors:u.errors,warnings:u.warnings}),p=i===`strict`?`error`:`warning`;try{t.validateJsonDepth(e,32)}catch(e){return u.add(`error`,`SECURITY_LIMIT`,e.message,[]),f()}if(!P(e)||!P(e.meta)||!Array.isArray(e.items))return u.add(`error`,`INVALID_ROOT`,`An OQSE file must be an object with "version", "meta" and "items" (array).`,[]),f();let m=structuredClone(e);if(m.$schema!==void 0&&typeof m.$schema!=`string`)return u.add(`error`,`INVALID_ROOT`,`"$schema" must be a string URL.`,[`$schema`]),f();if(typeof m.version!=`string`||!/^\d+\.\d+$/.test(m.version))return u.add(`error`,`INVALID_VERSION`,`Version must be in MAJOR.MINOR format (e.g. "1.0").`,[`version`]),f();let h=Number(m.version.split(`.`)[0]);if(h===0)return u.add(`error`,`UNSUPPORTED_VERSION`,`OQSE ${m.version} is a pre-release version; this library reads OQSE 1.x (convert the set to 1.0).`,[`version`]),f();if(h!==1&&u.add(`warning`,`UNSUPPORTED_VERSION`,`Unsupported MAJOR version ${m.version}; loading in best-effort mode.`,[`version`]),m.items.length>5e4)return u.add(`error`,`TOO_MANY_ITEMS`,`Maximum ${t.MAX_ITEMS} items per set.`,[`items`]),f();if(i===`load`){if(!N(m.meta,[`meta`,`assets`],u))return f();D(m.meta,`language`,[`meta`,`language`],u),m.items.forEach((e,t)=>P(e)&&D(e,`lang`,[`items`,t,`lang`],u,typeof e.id==`string`?e.id:void 0))}x(m.meta,u,i);let g=E(m.meta,u);if(!g)return f();let _={features:r.OFFICIAL_FEATURE_KEYS,itemProperties:r.OFFICIAL_ITEM_PROPERTIES,metaProperties:r.OFFICIAL_META_PROPERTIES};for(let[e,t]of Object.entries(_))for(let n of g.requirements?.[e]??[])!n.startsWith(`x-`)&&!t.includes(n)&&u.add(`warning`,`UNKNOWN_FEATURE`,`Unknown ${e===`features`?`feature`:`property`} "${n}" in requirements.${e} (ignored).`,[`meta`,`requirements`,e]);let b=new Set(g.requirements?.features??[]),w=b.has(`html`),T=b.has(`latex`);A(g.assets,[`meta`,`assets`],u,i),g.thumbnail&&!g.assets?.[g.thumbnail]&&(u.add(p,`MISSING_THUMBNAIL_ASSET`,`Thumbnail references non-existent asset "${g.thumbnail}".`,[`meta`,`thumbnail`]),i===`load`&&delete g.thumbnail);for(let[e,t]of c.metaRichText(g)){let n=w?null:a.findRawHtml(t,{latex:T});n&&(u.add(p,`RAW_HTML_NOT_ALLOWED`,F(n),e),i===`load`&&I(g,e.slice(1)))}let j=new Set([g.id]),M=[];m.items.forEach((e,t)=>{let r=[`items`,t],a=P(e)&&typeof e.id==`string`?e.id:void 0,c=P(e)?e.type:void 0;if(typeof c==`string`&&!c.startsWith(`x-`)&&!v.has(c)){let i=n.UnknownTypeItemSchema.safeParse(e);if(!i.success){u.addZod(i.error,`INVALID_ITEM`,r,a);return}if(j.has(i.data.id)){u.add(`error`,`DUPLICATE_ID`,`Duplicate ID "${i.data.id}" (IDs must be unique within the set, including meta.id).`,[...r,`id`],i.data.id);return}j.add(i.data.id),u.add(`warning`,`UNKNOWN_ITEM_TYPE`,`Unknown item type "${c}" (a newer OQSE version, or a typo; custom types use the "x-" prefix). The item is kept but not shown.`,[...r,`type`],a),d.push({index:t,item:structuredClone(e)});return}if(i===`load`&&P(e)&&!N(e,[...r,`assets`],u,a))return;let l=n.getItemSchema(e).safeParse(e);if(!l.success){u.addZod(l.error,`INVALID_ITEM`,r,a);return}let f=l.data;if(j.has(f.id)){u.add(`error`,`DUPLICATE_ID`,`Duplicate ID "${f.id}" (IDs must be unique within the set, including meta.id).`,[...r,`id`],f.id);return}j.add(f.id);for(let[e,t]of C(f))S.test(t)&&u.add(`warning`,`REVEALING_CHOICE_ID`,`Choice ID "${t}" gives the answer away (learners can see IDs); use an ID from the text or a random one.`,[...r,...e],f.id);let m=o.missingMustUnderstand(f,s.understood);if(m.length>0){u.add(`warning`,`MUST_UNDERSTAND`,`The item needs properties this application does not support (${m.join(`, `)}); it is kept but not shown.`,[...r,`mustUnderstand`],f.id),d.push({index:t,item:structuredClone(e)});return}A(f.assets,[...r,`assets`],u,i,f.id),k(f,r,g,w,T,u,p)&&M.push({item:f,index:t})});let L=M.map(e=>e.item),R=new Set(L.map(e=>e.id));for(let{item:e}of d)R.add(e.id);let z=new Set((g.sourceMaterials??[]).map(e=>e.id)),B=new Set((g.sourceMaterials??[]).filter(e=>e.set===g.id).map(e=>e.id));for(let{item:e,index:t}of M){let n=[`items`,t];for(let t of[`relatedItems`,`dependencyItems`]){let r=e[t];if(!r)continue;let a=r.filter(t=>t!==e.id&&R.has(t));a.length!==r.length&&(u.add(p,`DANGLING_REFERENCE`,`${t} contains IDs that do not exist in the set or reference the item itself.`,[...n,t],e.id),i===`load`&&(e[t]=a))}if(e.sources){let t=e.sources.filter(e=>z.has(e.id));t.length!==e.sources.length&&(u.add(p,`DANGLING_REFERENCE`,`sources reference source materials that do not exist in meta.sourceMaterials.`,[...n,`sources`],e.id),i===`load`&&(e.sources=t)),e.sources.forEach((t,r)=>{t.itemId!==void 0&&B.has(t.id)&&!R.has(t.itemId)&&(u.add(p,`DANGLING_REFERENCE`,`sources[${r}].itemId "${t.itemId}" does not exist in this set.`,[...n,`sources`,r,`itemId`],e.id),i===`load`&&delete t.itemId)})}}for(let e of l.detectFeatures({meta:g,items:L}))e!==`html`&&!b.has(e)&&u.add(`warning`,`UNDECLARED_FEATURE`,`The content uses "${e}", but meta.requirements.features does not declare it.`,[`meta`,`requirements`,`features`]);if(!T)for(let{item:e,index:t}of M){let n=c.itemRichText(e).find(([,e])=>l.looksLikeLatex(e));n&&u.add(`warning`,`LOOKS_LIKE_LATEX`,`The text looks like a LaTeX formula; if it is one, declare the "latex" feature (otherwise $ is an ordinary character).`,[`items`,t,...n[0]],e.id)}return O(g,M,u),{success:!0,data:{...m,meta:g,items:L},unsupportedItems:d,errors:u.errors,warnings:u.warnings}}function x(e,t,r){if(!Array.isArray(e.sourceMaterials))return;let i=[];e.sourceMaterials.forEach((e,a)=>{let o=[`meta`,`sourceMaterials`,a],s=n.SourceMaterialSchema.safeParse(e);if(!s.success){t.addZod(s.error,`INVALID_SOURCE`,o),r===`strict`&&i.push(e);return}let c=s.data;c.url===void 0&&c.doi===void 0&&c.isbn===void 0&&c.set===void 0&&t.add(`warning`,`SOURCE_WITHOUT_LOCATOR`,`Source "${c.id}" has none of url, doi, isbn, set: it can be cited only by its title.`,o),i.push(e)}),r===`load`&&(e.sourceMaterials=i)}var S=/(^|[^a-z])(correct|incorrect|right|wrong|answer|solution)([^a-z]|$)/i;function C(e){let t=[],n=e;for(let e of[`options`,`items`,`prompts`,`matches`,`categories`,`rows`,`columns`,`labels`,`events`,`zones`]){let r=n[e];Array.isArray(r)&&r.forEach((n,r)=>P(n)&&typeof n.id==`string`&&t.push([[e,r,`id`],n.id]))}if(e.type===`fill-in-select`&&P(n.blanks))for(let[e,r]of Object.entries(n.blanks))P(r)&&Array.isArray(r.options)&&r.options.forEach((n,r)=>P(n)&&typeof n.id==`string`&&t.push([[`blanks`,e,`options`,r,`id`],n.id]));return t}var w=new Set([`id`,`title`,`language`,`createdAt`,`updatedAt`]),T=new Set([`assets`,`tagDefinitions`,`translations`,`prerequisites`,`relatedSets`,`contributors`,`sourceMaterials`]);function E(e,t){let r=structuredClone(e);for(let e=0;e<50;e++){let e=n.OQSEMetaSchema.safeParse(r);if(e.success)return e.data;let i=[];for(let n of e.error.issues){let[e,r]=n.path;if(e===void 0||w.has(String(e)))return t.add(`error`,`INVALID_META`,n.message,[`meta`,...n.path]),null;t.add(`error`,`INVALID_META_FIELD`,`${n.message} (removed)`,[`meta`,...n.path]),i.push(T.has(String(e))&&r!==void 0?[e,r]:[e])}i.sort((e,t)=>Number(t[1]??0)-Number(e[1]??0));let a=new Set;for(let e of i){let t=e.join(`.`);if(a.has(t))continue;a.add(t);let[n,i]=e,o=r[n];i===void 0?delete r[n]:Array.isArray(o)?o.splice(Number(i),1):P(o)&&delete o[i]}}return null}function D(e,t,n,r,i){let a=e[t];typeof a==`string`&&a.includes(`_`)&&(e[t]=a.replace(/_/g,`-`),r.add(`warning`,`LANGUAGE_NORMALIZED`,`Language tag "${a}" written as "${e[t]}" (BCP 47 uses hyphens).`,n,i))}function O(t,n,r){let i=(e,t,n,i,a)=>{typeof e==`string`&&!t.includes(e)&&r.add(`warning`,`UNKNOWN_VALUE`,`Unknown value "${e}" (a newer OQSE version, or a typo): ${i}.`,n,a)},a=(t,n,r)=>{for(let[a,o]of Object.entries(t??{}))i(o.type,e.MEDIA_TYPES,[...n,a,`type`],`shown as a link`,r),o.subtitles?.forEach((t,o)=>i(t.kind,e.SUBTITLE_KINDS,[...n,a,`subtitles`,o,`kind`],`the track is not offered`,r))};a(t.assets,[`meta`,`assets`]),t.sourceMaterials?.forEach((t,n)=>i(t.kind,e.SOURCE_KINDS,[`meta`,`sourceMaterials`,n,`kind`],`treated as "other"`));for(let{item:t,index:r}of n)a(t.assets,[`items`,r,`assets`],t.id),i(t.pedagogy?.bloomLevel,e.BLOOM_LEVELS,[`items`,r,`pedagogy`,`bloomLevel`],`ignored`,t.id),i(t.pedagogy?.cognitiveLoad,e.COGNITIVE_LOADS,[`items`,r,`pedagogy`,`cognitiveLoad`],`ignored`,t.id)}function k(e,t,n,r,o,l,u){let d=!0;if(!r)for(let[n,r]of c.itemRichText(e)){let i=a.findRawHtml(r,{latex:o});i&&(l.add(`error`,`RAW_HTML_NOT_ALLOWED`,F(i),[...t,...n],e.id),d=!1)}if(`targetAsset`in e&&typeof e.targetAsset==`string`&&!e.type.startsWith(`x-`)){let r=s.resolveAsset(e.targetAsset,e,n),i=e.type===`pin-on-model`?`model`:`image`;r?r.type!==i&&(l.add(`error`,`INVALID_TARGET_ASSET`,`targetAsset "${e.targetAsset}" must be of type "${i}".`,[...t,`targetAsset`],e.id),d=!1):(l.add(`error`,`MISSING_TARGET_ASSET`,`targetAsset "${e.targetAsset}" does not exist in item.assets or meta.assets.`,[...t,`targetAsset`],e.id),d=!1)}let f=e.type===`timeline`?e.events:e.type===`categorize`?e.items:void 0;if(f){let n=f.map(e=>e.id);new Set(n).size!==n.length&&(l.add(`error`,`DUPLICATE_ID`,`Internal IDs must be unique within the item.`,[...t,e.type===`timeline`?`events`:`items`],e.id),d=!1)}if(e.type===`chess-puzzle`&&e.correctAnswers.some(e=>e.length%2==0)&&l.add(`warning`,`CHESS_SEQUENCE_LENGTH`,`Each move sequence should end with the learner's move (an odd number of moves; the application plays the replies).`,[...t,`correctAnswers`],e.id),e.type===`note`)for(let n of[`content`,`hiddenContent`]){let r=e[n];r&&i.findHeadings(i.splitLines(r)).some(e=>e.level===1)&&l.add(`warning`,`NOTE_HEADING_LEVEL`,`Headings inside a note should start at level 2 (##); the note title is level 1.`,[...t,n],e.id)}let p=e.type===`fill-in-blanks`||e.type===`fill-in-select`;for(let[n,r]of c.itemRichText(e)){for(let i of j(r)){if(/^https:\/\//i.test(i))continue;let r=/^http:\/\//i.test(i);l.add(r?`warning`:u,`INVALID_IMAGE_URL`,r?`Image "${i}" uses http:// (prefer https://).`:`Image "${i}" needs an absolute https:// URL (use <asset:key /> for other media).`,[...t,...n],e.id)}!(p&&n.length===1&&n[0]===`text`)&&/<blank:[a-zA-Z0-9_-]+\s*\/>/i.test(r)&&l.add(`warning`,`BLANK_OUTSIDE_TEXT`,`Blank tags belong only in the text of fill-in-blanks and fill-in-select (shown here as an empty line).`,[...t,...n],e.id)}for(let[r,i]of c.itemRichText(e))for(let o of a.findAssetKeys(i))s.resolveAsset(o,e,n)||l.add(`warning`,`MISSING_ASSET`,`<asset:${o} /> does not exist in item.assets or meta.assets.`,[...t,...r],e.id);for(let r of Object.keys(e.assets??{}))n.assets?.[r]&&l.add(`warning`,`ASSET_SHADOWED`,`Item asset "${r}" shadows a global asset with the same key; use unique keys.`,[...t,`assets`,r],e.id);return d}function A(e,t,n,r,i){for(let[a,o]of Object.entries(e??{}))o.type!==`image`||o.altText?.trim()||(n.add(r===`strict`?`error`:`warning`,`MISSING_ALT_TEXT`,`Image "${a}" has no altText (alternative text for screen readers).`,[...t,a,`altText`],i),r===`load`&&(o.altText=M(o.value)||a))}function j(e){return[...e.replace(/^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![\s\S]))/gm,``).replace(/`[^`\n]+`/g,``).matchAll(/!\[[^\]\n]*\]\(\s*<?([^)\s>]+)/g)].map(e=>e[1])}function M(e){return(e.split(/[?#]/)[0].split(`/`).pop()??``).replace(/\.[a-z0-9]+$/i,``).replace(/[-_]+/g,` `).trim()}function N(e,t,n,r){let i=e.assets;if(!P(i))return!0;let a={};for(let[e,o]of Object.entries(i)){let i=e.toLowerCase();if(i in a)return n.add(`error`,`ASSET_KEY_COLLISION`,`Asset keys collide after lowercasing ("${e}").`,[...t,e],r),!1;i!==e&&n.add(`warning`,`ASSET_KEY_NORMALIZED`,`Asset key "${e}" was converted to "${i}".`,[...t,e],r),a[i]=o}e.assets=a;for(let t of[`thumbnail`,`targetAsset`])typeof e[t]==`string`&&(e[t]=e[t].toLowerCase());return!0}function P(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function F(e){return`Raw HTML ${e} is not allowed unless the set declares the "html" feature (use Markdown instead).`}function I(e,t){let n=e;for(let e of t.slice(0,-1))n=n[e];delete n[t[t.length-1]]}exports.OQSEValidationError=u,exports.OQSE_VERSION=p,exports.SUPPORTED_OQSE_MAJOR_VERSION=f,exports.formatOQSEIssues=d,exports.loadOQSEFile=m,exports.safeValidateOQSEFile=h,exports.validateOQSEFile=_,exports.withUnsupportedItems=g;