@pie-players/pie-assessment-toolkit 0.3.63 → 0.3.64

package/dist/services/tts/text-processing.js

@@ -62,6 +62,122 @@ export const isNodeHiddenForTTS = (node, root) => {
     }
     return false;
 };
+/**
+ * Marks content that must be shown but never spoken — items where reading *is*
+ * the construct, such as decoding and spelling, where speaking the node hands
+ * over the answer.
+ *
+ * Not a PNP field: `prohibitedSupports` is the learner declining a support, while
+ * this is the item saying "not here, for anyone", so it overrides an entitlement
+ * rather than yielding to it.
+ *
+ * Shape follows QTI 3's `data-qti-suppress-tts` — an attribute on the content
+ * element, single-valued, vocabulary below. Element placement is what makes it
+ * work on undocked nodes and enforceable in the selection read-aloud path, which
+ * consults no catalog. The name follows PIE's `data-tts-*` family, and PIE reads
+ * only this spelling; importers map QTI's.
+ */
+export const TTS_SUPPRESS_ATTRIBUTE = "data-tts-suppress";
+const SUPPRESSES_COMPUTER_READ_ALOUD = new Set(["computer-read-aloud", "all"]);
+// `screen-reader` is in the vocabulary but is not ours: it asks the delivery
+// engine to hide the node from assistive technology, which is the host's job
+// (and is what `aria-hidden` above already covers on the way in). A node marked
+// only `screen-reader` is still legitimately machine-read aloud.
+const SUPPRESS_VALUES = new Set([
+    ...SUPPRESSES_COMPUTER_READ_ALOUD,
+    "screen-reader",
+]);
+const warnedSuppressValues = new Set();
+/**
+ * Whether this element forbids machine read-aloud of itself and its subtree.
+ *
+ * Unrecognized and empty values suppress rather than pass through, and say so once
+ * per distinct value: a typo that fell through would speak a word the item was
+ * measuring, invalidating the score with no visible symptom, whereas
+ * over-suppressing only withholds speech an author had already marked as withheld.
+ */
+export const isElementSuppressedForTTS = (element) => {
+    const raw = element.getAttribute?.(TTS_SUPPRESS_ATTRIBUTE);
+    if (raw === null || raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    if (SUPPRESSES_COMPUTER_READ_ALOUD.has(value))
+        return true;
+    if (SUPPRESS_VALUES.has(value))
+        return false;
+    if (!warnedSuppressValues.has(value)) {
+        warnedSuppressValues.add(value);
+        console.warn(`[tts] ${TTS_SUPPRESS_ATTRIBUTE}="${raw}" is not one of ${Array.from(SUPPRESS_VALUES).join(", ")}; suppressing read-aloud for this content anyway, because a suppression attribute that fails open would leak the answer to items where reading is the construct. Correct the value to silence this.`);
+    }
+    return true;
+};
+export const isNodeSuppressedForTTS = (node, root) => {
+    let current = node.nodeType === 1
+        ? node
+        : node.parentElement;
+    while (current) {
+        if (isElementSuppressedForTTS(current))
+            return true;
+        if (root && current === root)
+            break;
+        current = current.parentElement;
+    }
+    return false;
+};
+/**
+ * The predicate every speech-producing path filters on: hidden *or* suppressed.
+ *
+ * Kept distinct from `isNodeHiddenForTTS`, which stays a question about
+ * visibility — suppressed content is visible on purpose, and the highlight
+ * geometry resolvers that ask "can the candidate see this" must keep getting
+ * the visibility answer rather than this one.
+ */
+export const isNodeExcludedFromSpeech = (node, root) => isNodeHiddenForTTS(node, root) || isNodeSuppressedForTTS(node);
+/**
+ * Text of a range with the parts that must not be spoken removed.
+ *
+ * `Range.toString()` is not usable for speech: it is pure character extraction
+ * and honours no DOM filter at all, so it happily returns suppressed — and
+ * hidden — text. The selection read-aloud path is a text-in path rather than a
+ * DOM walk, which makes this the only place its content can be filtered.
+ *
+ * `filtered` reports whether anything was dropped, so a caller can tell "the
+ * candidate selected nothing speakable" apart from "the candidate selected
+ * nothing".
+ */
+export const collectRangeTextForSpeech = (range, root) => {
+    if (typeof document === "undefined" ||
+        typeof document.createTreeWalker !==
+            "function" ||
+        typeof NodeFilter === "undefined" ||
+        typeof range.intersectsNode !== "function") {
+        // Degraded, and deliberately not silent about the difference: callers still
+        // enforce whole-selection suppression from the range's common ancestor, so
+        // the construct guard holds even here. What is lost is per-node filtering
+        // of a selection that only partly overlaps suppressed content.
+        return { text: range.toString(), filtered: false };
+    }
+    const parts = [];
+    let filtered = false;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let current = walker.nextNode();
+    while (current) {
+        const textNode = current;
+        if (range.intersectsNode(textNode)) {
+            if (isNodeExcludedFromSpeech(textNode, root)) {
+                filtered = true;
+            }
+            else {
+                const raw = textNode.textContent || "";
+                const start = textNode === range.startContainer ? range.startOffset : 0;
+                const end = textNode === range.endContainer ? range.endOffset : raw.length;
+                parts.push(raw.slice(start, end));
+            }
+        }
+        current = walker.nextNode();
+    }
+    return { text: parts.join(""), filtered };
+};
 export const shouldInsertWordBoundarySpace = (previousChar, nextChar, options) => {
     if (!previousChar || !nextChar)
         return false;
@@ -111,7 +227,7 @@ export const collectVisibleTextAndMap = (element, options) => {
     while (current) {
         const textNode = current;
         const parent = textNode.parentElement;
-        if (parent && !isNodeHiddenForTTS(textNode, element)) {
+        if (parent && !isNodeExcludedFromSpeech(textNode, element)) {
             const raw = textNode.textContent || "";
             const firstVisibleMatch = raw.match(/\S/);
             const firstVisibleChar = firstVisibleMatch ? firstVisibleMatch[0] : null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-assessment-toolkit",
-	"version": "0.3.63",
+	"version": "0.3.64",
 	"type": "module",
 	"description": "PIE assessment toolkit: composable services + reference implementation for assessment players and tool coordination",
 	"license": "MIT",
@@ -75,15 +75,15 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-calculator": "0.3.63",
-		"@pie-players/pie-context": "0.3.63",
-		"@pie-players/pie-players-shared": "0.3.63",
-		"@pie-players/pie-tts": "0.3.63",
+		"@pie-players/pie-calculator": "0.3.64",
+		"@pie-players/pie-context": "0.3.64",
+		"@pie-players/pie-players-shared": "0.3.64",
+		"@pie-players/pie-tts": "0.3.64",
 		"speech-rule-engine": "^5.0.0-rc.4"
 	},
 	"peerDependencies": {
-		"@pie-players/pie-calculator-desmos": "0.3.63",
-		"@pie-players/tts-client-server": "0.3.63"
+		"@pie-players/pie-calculator-desmos": "0.3.64",
+		"@pie-players/tts-client-server": "0.3.64"
 	},
 	"peerDependenciesMeta": {
 		"@pie-players/pie-calculator-desmos": {
@@ -96,8 +96,8 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.6",
 		"@happy-dom/global-registrator": "^20.11.1",
-		"@pie-players/pie-calculator-desmos": "0.3.63",
-		"@pie-players/tts-client-server": "0.3.63",
+		"@pie-players/pie-calculator-desmos": "0.3.64",
+		"@pie-players/tts-client-server": "0.3.64",
 		"svelte": "^5.56.8",
 		"typescript": "^5.9.3"
 	},