@pie-players/pie-assessment-toolkit 0.3.67 → 0.3.68

package/dist/services/tool-context.js

@@ -40,185 +40,226 @@ export function isRubricContext(context) {
 export function isElementContext(context) {
     return context.level === "element";
 }
+const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
 /**
- * Helper to extract text content from an item or element for analysis
+ * A config's `models` as a list, whether it was authored as an array or as a
+ * record keyed by element id. Both forms are in the wild.
  */
-export function extractTextContent(context) {
+function normalizeModels(modelsRaw) {
+    if (Array.isArray(modelsRaw))
+        return modelsRaw;
+    if (modelsRaw && typeof modelsRaw === "object") {
+        return Object.values(modelsRaw);
+    }
+    return [];
+}
+/**
+ * Push every string a model carries, one level into its arrays of objects.
+ *
+ * The depth is deliberate rather than a full walk: math and prose live in a
+ * model's own fields (`prompt`, `label`) and in its choice/row arrays, which is
+ * one level down. Recursing further would pull in ids, keys and config flags.
+ */
+function collectModelText(model, push) {
+    if (!model || typeof model !== "object")
+        return;
+    for (const value of Object.values(model)) {
+        if (typeof value === "string")
+            push(value);
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                if (entry && typeof entry === "object") {
+                    for (const nested of Object.values(entry)) {
+                        if (typeof nested === "string")
+                            push(nested);
+                    }
+                }
+            }
+        }
+    }
+}
+/** Push the markup of every element snippet in a config's `elements` map. */
+function collectElementsText(elements, push) {
+    if (!elements || typeof elements !== "object")
+        return;
+    for (const elementMarkup of Object.values(elements)) {
+        if (typeof elementMarkup === "string")
+            push(elementMarkup);
+    }
+}
+/**
+ * The authored content a context carries, for the content heuristics below.
+ *
+ * Each level differs only in which fields it reads: an element reads its own
+ * markup snippet and the one model bearing its id, an item and a passage read
+ * their whole config and every model. The traversal itself is shared, so a new
+ * place content can hide is added once.
+ *
+ * `transform` decides what the caller gets. {@link extractTextContent} strips
+ * tags, which is right for prose keyword matching and wrong for structural
+ * matching: a MathML item's only math signal *is* the `<math>` tag, and stripping
+ * first left `hasMathContent`'s MathML pattern unreachable.
+ */
+function extractContent(context, transform) {
+    const textChunks = [];
+    const push = (text) => {
+        textChunks.push(transform(text));
+    };
+    const joined = () => textChunks.filter(Boolean).join(" ").trim();
     if (isElementContext(context)) {
         const config = context.item.config;
         if (!config)
             return "";
-        const textChunks = [];
-        const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
-        // Try to find element markup by element id.
         const elementMarkup = config.elements?.[context.elementId];
-        if (elementMarkup) {
-            if (typeof elementMarkup === "string") {
-                textChunks.push(stripHtml(elementMarkup));
-            }
-        }
-        // Also inspect model data keyed by this element id.
-        // In many items, math appears in model.prompt/labels rather than elements[elementId].
-        const modelsRaw = config.models;
-        const models = Array.isArray(modelsRaw)
-            ? modelsRaw
-            : modelsRaw && typeof modelsRaw === "object"
-                ? Object.values(modelsRaw)
-                : [];
-        const model = models.find((m) => m && typeof m === "object" && m.id === context.elementId);
-        if (model) {
-            for (const value of Object.values(model)) {
-                if (typeof value === "string") {
-                    textChunks.push(stripHtml(value));
-                }
-                if (Array.isArray(value)) {
-                    for (const entry of value) {
-                        if (entry && typeof entry === "object") {
-                            for (const nested of Object.values(entry)) {
-                                if (typeof nested === "string") {
-                                    textChunks.push(stripHtml(nested));
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        return textChunks.filter(Boolean).join(" ").trim();
+        if (typeof elementMarkup === "string")
+            push(elementMarkup);
+        // Model data keyed by this element id: in many items the math is in
+        // `model.prompt`/labels rather than in `elements[elementId]`.
+        const model = normalizeModels(config.models).find((candidate) => !!candidate &&
+            typeof candidate === "object" &&
+            candidate.id === context.elementId);
+        collectModelText(model, push);
+        return joined();
     }
     if (isItemContext(context)) {
-        const item = context.item;
-        if (!item?.config)
+        const config = context.item?.config;
+        if (!config)
             return "";
-        const config = item.config;
-        const textChunks = [];
-        const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
-        // Primary item markup
-        if (typeof config.markup === "string") {
-            textChunks.push(stripHtml(config.markup));
+        if (typeof config.markup === "string")
+            push(config.markup);
+        collectElementsText(config.elements, push);
+        for (const model of normalizeModels(config.models)) {
+            collectModelText(model, push);
         }
-        // Element markup snippets
-        const elements = config.elements;
-        if (elements && typeof elements === "object") {
-            for (const elementMarkup of Object.values(elements)) {
-                if (typeof elementMarkup === "string") {
-                    textChunks.push(stripHtml(elementMarkup));
-                }
-            }
-        }
-        // Model-level text (prompts, labels, etc.)
-        const modelsRaw = config.models;
-        const models = Array.isArray(modelsRaw)
-            ? modelsRaw
-            : modelsRaw && typeof modelsRaw === "object"
-                ? Object.values(modelsRaw)
-                : [];
-        for (const model of models) {
-            if (!model || typeof model !== "object")
-                continue;
-            for (const value of Object.values(model)) {
-                if (typeof value === "string") {
-                    textChunks.push(stripHtml(value));
-                }
-                if (Array.isArray(value)) {
-                    for (const entry of value) {
-                        if (entry && typeof entry === "object") {
-                            for (const nested of Object.values(entry)) {
-                                if (typeof nested === "string") {
-                                    textChunks.push(stripHtml(nested));
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        return textChunks.filter(Boolean).join(" ").trim();
+        return joined();
     }
     if (isPassageContext(context)) {
-        const passage = context.passage;
-        if (!passage?.config)
+        const config = context.passage?.config;
+        if (!config)
             return "";
-        const config = passage.config;
-        const textChunks = [];
-        const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
-        // Primary passage markup/content
-        if (typeof config.markup === "string") {
-            textChunks.push(stripHtml(config.markup));
-        }
-        if (typeof config.content === "string") {
-            textChunks.push(stripHtml(config.content));
-        }
-        if (typeof config.prompt === "string") {
-            textChunks.push(stripHtml(config.prompt));
-        }
-        // Element markup snippets
-        const elements = config.elements;
-        if (elements && typeof elements === "object") {
-            for (const elementMarkup of Object.values(elements)) {
-                if (typeof elementMarkup === "string") {
-                    textChunks.push(stripHtml(elementMarkup));
-                }
-            }
+        for (const field of ["markup", "content", "prompt"]) {
+            const value = config[field];
+            if (typeof value === "string")
+                push(value);
         }
-        // Model-level text (prompts, labels, etc.)
-        const modelsRaw = config.models;
-        const models = Array.isArray(modelsRaw)
-            ? modelsRaw
-            : modelsRaw && typeof modelsRaw === "object"
-                ? Object.values(modelsRaw)
-                : [];
-        for (const model of models) {
-            if (!model || typeof model !== "object")
-                continue;
-            for (const value of Object.values(model)) {
-                if (typeof value === "string") {
-                    textChunks.push(stripHtml(value));
-                }
-                if (Array.isArray(value)) {
-                    for (const entry of value) {
-                        if (entry && typeof entry === "object") {
-                            for (const nested of Object.values(entry)) {
-                                if (typeof nested === "string") {
-                                    textChunks.push(stripHtml(nested));
-                                }
-                            }
-                        }
-                    }
-                }
-            }
+        collectElementsText(config.elements, push);
+        for (const model of normalizeModels(config.models)) {
+            collectModelText(model, push);
         }
-        return textChunks.filter(Boolean).join(" ").trim();
+        return joined();
     }
     if (isRubricContext(context)) {
+        // No model walk: a rubric block is authored prose, so its text is one
+        // string — the embedded passage's markup when it has one, else its content.
         const rubric = context.rubricBlock;
-        // If rubric has embedded passage, extract from passage config
         if (rubric.passage?.config) {
-            const markup = rubric.passage.config.markup || "";
-            return markup.replace(/<[^>]*>/g, " ").trim();
+            return transform(rubric.passage.config.markup || "");
         }
-        // Otherwise, use simple content string
-        const content = rubric.content || "";
-        return content.replace(/<[^>]*>/g, " ").trim();
+        return transform(rubric.content || "");
     }
     return "";
 }
+/** The plain text a context carries, tags removed. */
+export function extractTextContent(context) {
+    return extractContent(context, stripHtml);
+}
+/**
+ * The authored markup a context carries, tags intact.
+ *
+ * For indicators that live in the markup rather than in the prose — `<math>`
+ * above all, whose whole signal is the element name.
+ */
+export function extractMarkupContent(context) {
+    return extractContent(context, (value) => value);
+}
 /**
  * Helper to check if context contains mathematical content
  * (Basic heuristic - can be overridden by tools)
  */
+/**
+ * Chemical element symbols.
+ *
+ * A real set rather than `[A-Z][a-z]?`: that shape matches "It", "In", "He" and
+ * "A", which is why the science gate used to answer `true` for any prose that
+ * began a sentence.
+ */
+const ELEMENT_SYMBOLS = new Set([
+    "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne", "Na", "Mg", "Al", "Si",
+    "P", "S", "Cl", "Ar", "K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co",
+    "Ni", "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr",
+    "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn", "Sb", "Te", "I",
+    "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd", "Pm", "Sm", "Eu", "Gd", "Tb", "Dy",
+    "Ho", "Er", "Tm", "Yb", "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au",
+    "Hg", "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th", "Pa", "U",
+    "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm", "Md", "No", "Lr",
+]);
+/** A word that could be a formula: capitalised groups with optional counts. */
+const FORMULA_CANDIDATE = /\b[A-Z][A-Za-z]*\d*(?:[A-Z][A-Za-z]*\d*)*\b/g;
+const FORMULA_GROUP = /([A-Z][a-z]?)(\d*)/g;
+/**
+ * Whether the text contains something only a chemical formula looks like.
+ *
+ * A token qualifies when every one of its groups is a real element symbol *and*
+ * it either names two or more of them or carries a count — `NaCl`, `CO2`, `H2O`,
+ * `C6H12O6`. A lone symbol never qualifies: "In", "He", "As" and "At" are
+ * ordinary English words, and a single-letter "I" or "A" more so.
+ */
+function hasChemicalFormula(text) {
+    for (const candidate of text.match(FORMULA_CANDIDATE) ?? []) {
+        FORMULA_GROUP.lastIndex = 0;
+        let groups = 0;
+        let hasCount = false;
+        let consumed = 0;
+        let valid = true;
+        let match = FORMULA_GROUP.exec(candidate);
+        while (match !== null) {
+            if (match[0] === "")
+                break;
+            if (!ELEMENT_SYMBOLS.has(match[1])) {
+                valid = false;
+                break;
+            }
+            groups += 1;
+            if (match[2])
+                hasCount = true;
+            consumed += match[0].length;
+            match = FORMULA_GROUP.exec(candidate);
+        }
+        // Every character has to belong to a group, or the token was only
+        // formula-shaped at its start ("Hello" -> "He" + "llo").
+        if (valid && consumed === candidate.length && (groups > 1 || hasCount)) {
+            return true;
+        }
+    }
+    return false;
+}
 export function hasMathContent(context) {
-    const text = extractTextContent(context);
-    // Look for common math indicators
-    const mathIndicators = [
+    // Structural signals live in the markup: stripping tags first is what left the
+    // MathML pattern unable to match anything at all.
+    const markup = extractMarkupContent(context);
+    const structuralIndicators = [
         /<math[>\s]/i, // MathML
         /\\\[([^\]]+)\\\]/, // LaTeX display math
         /\$\$[^$]+\$\$/, // LaTeX display math ($$...$$)
         /\\\(/, // LaTeX inline math
-        /[+\-*/=<>≤≥∑∫√π]/, // Math symbols
-        /\d+\s*[+\-*/=]\s*\d+/, // Simple arithmetic
     ];
-    return mathIndicators.some((pattern) => pattern.test(text));
+    if (structuralIndicators.some((pattern) => pattern.test(markup)))
+        return true;
+    const text = extractTextContent(context);
+    // No bare-operator pattern. `/[+\-*/=<>≤≥∑∫√π]/` matched any hyphen or slash,
+    // so "well-known" and "and/or" made every item mathematical and this predicate
+    // answered `true` for essentially all content — a gate that does not gate. An
+    // operator counts only with operands around it, or when the character has no
+    // prose reading at all.
+    const textIndicators = [
+        /[≤≥≠±×÷∑∫√∞π]/, // Symbols with no prose reading
+        /\d+\s*[+\-*/×÷=]\s*\d+/, // Simple arithmetic
+        /\d\s*[<>]\s*\d/, // Numeric comparison
+        /\b\d+\s*\/\s*\d+\b/, // Fractions
+        /\b\d+(?:\.\d+)?\s*%/, // Percentages
+        /\^\s*\d/, // Exponents
+    ];
+    return textIndicators.some((pattern) => pattern.test(text));
 }
 /**
  * Helper to check if context contains choice-based interactions
@@ -281,14 +322,18 @@ export function hasReadableText(context) {
  */
 export function hasScienceContent(context) {
     const text = extractTextContent(context);
-    // Look for common science indicators
+    // The element-symbol pattern used to be `/\b[A-Z][a-z]?\d*\b/`, which matches
+    // any one- or two-letter capitalised word: "It", "In", "A", "No". Every item
+    // beginning a sentence with one read as science.
+    if (hasChemicalFormula(text))
+        return true;
+    if (/[A-Z][a-z]?[\u2080-\u2089]/.test(text))
+        return true; // Subscripted: H₂O, CO₂
     const scienceIndicators = [
-        /chemistry|chemical|element|atom|molecule|compound/i,
-        /periodic\s+table/i,
-        /H₂O|CO₂|NaCl|O₂|N₂/i, // Chemical formulas
-        /\b[A-Z][a-z]?\d*\b/, // Element symbols (H, He, Li, etc.)
-        /biology|organism|cell|DNA|RNA|protein/i,
-        /physics|force|energy|velocity|acceleration/i,
+        /chemistry|chemical|molecule|compound|periodic\s+table/i,
+        /\bchemical\s+element\b|\belement\s+symbol\b/i,
+        /biology|organism|\bDNA\b|\bRNA\b|protein|photosynthesis|ecosystem/i,
+        /physics|\bforce\b|\benergy\b|velocity|acceleration|momentum/i,
     ];
     return scienceIndicators.some((pattern) => pattern.test(text));
 }

package/dist/services/tool-icons.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in icon markup for toolbar buttons, keyed by the names registrations use.
+ *
+ * A registration names an icon rather than shipping markup, so a host swapping the
+ * button chrome gets one consistent set. A name with no entry here renders no icon
+ * at all, and an icon-only button with no icon is a blank square — so a registration
+ * naming an icon and this map are one change, not two.
+ *
+ * Names are generic shapes ("book-open", "beaker"), never capability names. Core
+ * naming a capability is what the composition layer exists to prevent.
+ *
+ * Exported through `tools/internal` as well: a registration composing a selection
+ * gateway renders its own buttons and has to draw the same icon the toolbar button
+ * draws, or the learner sees two unrelated affordances for one tool.
+ */
+export declare const TOOL_FALLBACK_ICONS: Readonly<Record<string, string>>;
+/** Icon markup for `name`, or `null` when nothing built in matches. */
+export declare function resolveFallbackToolIcon(name: string): string | null;

package/dist/services/tool-icons.js

@@ -0,0 +1,31 @@
+/**
+ * Built-in icon markup for toolbar buttons, keyed by the names registrations use.
+ *
+ * A registration names an icon rather than shipping markup, so a host swapping the
+ * button chrome gets one consistent set. A name with no entry here renders no icon
+ * at all, and an icon-only button with no icon is a blank square — so a registration
+ * naming an icon and this map are one change, not two.
+ *
+ * Names are generic shapes ("book-open", "beaker"), never capability names. Core
+ * naming a capability is what the composition layer exists to prevent.
+ *
+ * Exported through `tools/internal` as well: a registration composing a selection
+ * gateway renders its own buttons and has to draw the same icon the toolbar button
+ * draws, or the learner sees two unrelated affordances for one tool.
+ */
+export const TOOL_FALLBACK_ICONS = {
+    calculator: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M7 2h10a2 2 0 0 1 2 2v16a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2Zm0 2v4h10V4H7Zm0 6v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Zm-8 4v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Zm-8 4v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Z" fill="currentColor"/></svg>',
+    "volume-up": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 3.23v2.06A7.002 7.002 0 0 1 19 12a7 7 0 0 1-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77Zm-2 17.75V3L7 8H3v8h4l5 5Zm4.5-9a4.5 4.5 0 0 0-2.5-4.03v8.05A4.5 4.5 0 0 0 16.5 12Z" fill="currentColor"/></svg>',
+    swatch: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 3a9 9 0 1 0 9 9c0-.55-.45-1-1-1h-2.5a1.5 1.5 0 0 1 0-3H20a1 1 0 0 0 1-1 8.99 8.99 0 0 0-9-4Zm-5.5 9A1.5 1.5 0 1 1 8 13.5 1.5 1.5 0 0 1 6.5 12Zm3-4A1.5 1.5 0 1 1 11 9.5 1.5 1.5 0 0 1 9.5 8Zm5 0A1.5 1.5 0 1 1 16 9.5 1.5 1.5 0 0 1 14.5 8Z" fill="currentColor"/></svg>',
+    "chart-bar": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4.75 5a.76.76 0 0 1 .75.75v11c0 .438.313.75.75.75h13a.76.76 0 0 1 .696 1.039.74.74 0 0 1-.696.461h-13C5 19 4 18 4 16.75v-11A.74.74 0 0 1 4.75 5ZM8 8.25a.74.74 0 0 1 .75-.75h6.5a.76.76 0 0 1 .696 1.039.74.74 0 0 1-.696.461h-6.5A.722.722 0 0 1 8 8.25Zm.75 2.25h4.5a.76.76 0 0 1 .696 1.039.74.74 0 0 1-.696.461h-4.5a.723.723 0 0 1-.75-.75.74.74 0 0 1 .75-.75Zm0 3h8.5a.76.76 0 0 1 .696 1.039.74.74 0 0 1-.696.461h-8.5a.723.723 0 0 1-.75-.75.74.74 0 0 1 .75-.75Z" fill="currentColor"/></svg>',
+    beaker: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M5 21c-.85 0-1.454-.38-1.813-1.137-.358-.759-.27-1.463.263-2.113L9 11V5H8a.968.968 0 0 1-.713-.287A.968.968 0 0 1 7 4c0-.283.096-.52.287-.712A.968.968 0 0 1 8 3h8c.283 0 .52.096.712.288.192.191.288.429.288.712s-.096.52-.288.713A.968.968 0 0 1 16 5h-1v6l5.55 6.75c.533.65.62 1.354.262 2.113C20.454 20.62 19.85 21 19 21H5Zm2-3h10l-3.4-4h-3.2L7 18Zm-2 1h14l-6-7.3V5h-2v6.7L5 19Z" fill="currentColor"/></svg>',
+    protractor: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m6.75 21-.25-2.2 2.85-7.85a3.95 3.95 0 0 0 1.75.95l-2.75 7.55L6.75 21Zm10.5 0-1.6-1.55-2.75-7.55a3.948 3.948 0 0 0 1.75-.95l2.85 7.85-.25 2.2ZM12 11a2.893 2.893 0 0 1-2.125-.875A2.893 2.893 0 0 1 9 8c0-.65.188-1.23.563-1.737A2.935 2.935 0 0 1 11 5.2V3h2v2.2c.583.2 1.063.554 1.438 1.063C14.812 6.77 15 7.35 15 8c0 .833-.292 1.542-.875 2.125A2.893 2.893 0 0 1 12 11Zm0-2c.283 0 .52-.096.713-.287A.967.967 0 0 0 13 8a.967.967 0 0 0-.287-.713A.968.968 0 0 0 12 7a.968.968 0 0 0-.713.287A.967.967 0 0 0 11 8c0 .283.096.52.287.713.192.191.43.287.713.287Z" fill="currentColor"/></svg>',
+    "bars-3": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M6.85 15c.517 0 .98-.15 1.388-.45.408-.3.695-.692.862-1.175l.375-1.15c.267-.8.2-1.537-.2-2.213C8.875 9.337 8.3 9 7.55 9H4.025l.475 3.925c.083.583.346 1.075.787 1.475.442.4.963.6 1.563.6Zm10.3 0c.6 0 1.12-.2 1.563-.6.441-.4.704-.892.787-1.475L19.975 9h-3.5c-.75 0-1.325.342-1.725 1.025-.4.683-.467 1.425-.2 2.225l.35 1.125c.167.483.454.875.862 1.175.409.3.871.45 1.388.45Zm-10.3 2c-1.1 0-2.063-.363-2.887-1.088a4.198 4.198 0 0 1-1.438-2.737L2 9H1V7h6.55c.733 0 1.404.18 2.013.537A3.906 3.906 0 0 1 11 9h2.025c.35-.617.83-1.104 1.438-1.463A3.892 3.892 0 0 1 16.474 7H23v2h-1l-.525 4.175a4.198 4.198 0 0 1-1.438 2.737A4.238 4.238 0 0 1 17.15 17c-.95 0-1.804-.27-2.562-.813A4.234 4.234 0 0 1 13 14.026l-.375-1.125a21.35 21.35 0 0 1-.1-.363 4.926 4.926 0 0 1-.1-.537h-.85c-.033.2-.067.363-.1.488a21.35 21.35 0 0 1-.1.362L11 14a4.3 4.3 0 0 1-1.588 2.175A4.258 4.258 0 0 1 6.85 17Z" fill="currentColor"/></svg>',
+    ruler: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m8.8 10.95 2.15-2.175-1.4-1.425-1.1 1.1-1.4-1.4 1.075-1.1L7 4.825 4.825 7 8.8 10.95Zm8.2 8.225L19.175 17l-1.125-1.125-1.1 1.075-1.4-1.4 1.075-1.1-1.425-1.4-2.15 2.15L17 19.175ZM7.25 21H3v-4.25l4.375-4.375L2 7l5-5 5.4 5.4 3.775-3.8c.2-.2.425-.35.675-.45a2.068 2.068 0 0 1 1.55 0c.25.1.475.25.675.45L20.4 4.95c.2.2.35.425.45.675.1.25.15.508.15.775a1.975 1.975 0 0 1-.6 1.425l-3.775 3.8L22 17l-5 5-5.375-5.375L7.25 21ZM5 19h1.4l9.8-9.775L14.775 7.8 5 17.6V19Z" fill="currentColor"/></svg>',
+    "book-open": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 6.25a6.6 6.6 0 0 0-2.3-1.32A8.6 8.6 0 0 0 7 4.5c-.63 0-1.25.06-1.85.18-.6.12-1.19.3-1.76.54a1.5 1.5 0 0 0-.93 1.4v10.1c0 .52.26.98.68 1.24.42.26.92.28 1.35.06.36-.18.75-.31 1.18-.4.42-.09.86-.13 1.33-.13.78 0 1.53.14 2.24.42.7.28 1.35.7 1.93 1.24l.83-.75.83.75c.58-.54 1.22-.96 1.93-1.24a6.1 6.1 0 0 1 2.24-.42c.47 0 .91.04 1.33.13.43.09.82.22 1.18.4.43.22.93.2 1.35-.06.42-.26.68-.72.68-1.24V6.62c0-.6-.36-1.15-.93-1.4a9.3 9.3 0 0 0-1.76-.54A9.8 9.8 0 0 0 17 4.5a8.6 8.6 0 0 0-2.7.43A6.6 6.6 0 0 0 12 6.25Zm1 10.06V8.02c.55-.5 1.16-.88 1.84-1.13A6 6 0 0 1 17 6.5c.45 0 .89.04 1.32.11.43.08.85.19 1.26.34v9.24a8.2 8.2 0 0 0-1.28-.24A10 10 0 0 0 17 15.85c-.72 0-1.42.09-2.09.26a7.7 7.7 0 0 0-1.91.8Zm-2 0a7.7 7.7 0 0 0-1.91-.8 8.4 8.4 0 0 0-2.09-.26c-.44 0-.87.02-1.3.07-.43.05-.86.13-1.28.24V6.95c.41-.15.83-.26 1.26-.34A7.7 7.7 0 0 1 7 6.5c.76 0 1.48.13 2.16.39.68.25 1.29.63 1.84 1.13Z" fill="currentColor"/></svg>',
+    photo: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 21c-.55 0-1.02-.2-1.41-.59A1.93 1.93 0 0 1 2 19V5c0-.55.2-1.02.59-1.41A1.93 1.93 0 0 1 4 3h16c.55 0 1.02.2 1.41.59.39.39.59.86.59 1.41v14c0 .55-.2 1.02-.59 1.41-.39.39-.86.59-1.41.59H4Zm0-2h16V5H4v14Zm1.5-2.5h13l-4.1-5.47-3.4 4.47-2.5-3.25L5.5 16.5ZM8.5 10a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z" fill="currentColor"/></svg>',
+};
+/** Icon markup for `name`, or `null` when nothing built in matches. */
+export function resolveFallbackToolIcon(name) {
+    return TOOL_FALLBACK_ICONS[name] || null;
+}

package/dist/services/tool-providers/DesmosToolProvider.d.ts

@@ -10,10 +10,15 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import type { CalculatorProvider, DesmosCalculatorConfig } from "@pie-players/pie-calculator";
+import type { CalculatorProvider } from "@pie-players/pie-calculator";
 import type { ToolProviderApi, ToolProviderCapabilities } from "./ToolProviderApi.js";
 /**
  * Desmos tool provider configuration
+ *
+ * Auth and telemetry only. Per-calculator Desmos options are owned by the
+ * calculator component, which derives them from the calculator type and passes
+ * them to `createCalculator()` directly — this provider never sees that config,
+ * so a defaults field here would silently do nothing.
  */
 export interface DesmosToolProviderConfig {
     /**
@@ -31,10 +36,6 @@ export interface DesmosToolProviderConfig {
      * @example 'https://api.myapp.com/tools/desmos/auth'
      */
     proxyEndpoint?: string;
-    /**
-     * Default calculator configuration applied to all instances
-     */
-    defaultConfig?: DesmosCalculatorConfig;
     /**
      * Optional telemetry callback for tool/backend instrumentation.
      */

package/dist/services/tool-request.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Tool open requests.
+ *
+ * A surface that acts on the learner's current selection has to hand that selection
+ * to a tool it does not mount. The annotation strip is the case PIE ships: it is a
+ * section-scoped singleton in its own shadow root, and the tool it opens is mounted
+ * by a toolbar under a scoped instance id the strip cannot construct.
+ *
+ * Resolution is a claim, not a broadcast. Each toolbar registers as the target for its
+ * placement level, and a request reaches exactly one: the first target that currently
+ * hosts the tool, preferring section scope. A broadcast would open a panel in every
+ * toolbar whose scope contains the selection, which in a section player is the item
+ * card's toolbar and the section's both.
+ *
+ * `params` reaches the tool through the same seam a host-registered context resolver
+ * feeds, so receiving a request costs a tool nothing: whatever already reads
+ * `getToolRenderParams` sees it.
+ *
+ * Core names no capability. The requester supplies the tool id, which is why the
+ * pairing of a selection action to a dictionary lives in the composition layer.
+ */
+import type { ToolPlacementLevel } from "./tools-config-normalizer.js";
+/** Level a request resolves against when the requester names none. */
+export declare const DEFAULT_TOOL_REQUEST_LEVEL: ToolPlacementLevel;
+export interface ToolOpenRequest {
+    /** Unscoped tool id, as the registration declares it. */
+    toolId: string;
+    /**
+     * Merged over the host-resolved render params for this tool rather than
+     * replacing them, so a request carrying a term to look up leaves the endpoint
+     * the host configured in place.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Placement level of the toolbar that should open the tool.
+     *
+     * Naming one is a constraint and is honoured strictly: a requester that asks for
+     * `"item"` gets an item toolbar or nothing. Leaving it out asks for whichever
+     * toolbar hosts the tool, preferring `"section"` — the level at which a whole
+     * section shares one instance. A host that places a tool only at item scope would
+     * otherwise have the affordance silently disappear, and configuring a level here
+     * to match a placement made elsewhere is a step it has no reason to expect.
+     *
+     * At `"item"` and `"passage"` a section holds one target per card, and the first
+     * registered one that hosts the tool claims the request. A requester that needs a
+     * particular card's instance cannot express that here, and the gateway PIE ships
+     * does not need to: the strip is a section-scoped singleton acting on passage
+     * selections, so the selection belongs to no card, and what opens is a floating
+     * shell rather than anything rendered inside one.
+     */
+    level?: ToolPlacementLevel;
+}
+export interface ToolRequestTarget {
+    /** The placement level this toolbar renders. */
+    level: ToolPlacementLevel;
+    /** Whether this toolbar currently renders the tool, per its own policy pass. */
+    hostsTool: (toolId: string) => boolean;
+    /**
+     * Show the tool with `params` already applied.
+     *
+     * Show rather than toggle: a learner who selects a second word and asks for the
+     * dictionary again is asking for the dictionary, and a toggle would close it.
+     */
+    open: (toolId: string, params?: Record<string, unknown>) => void;
+}
+/**
+ * Registry of the toolbars a request can reach.
+ *
+ * Insertion order is the tie-break within a level, so a target registered while an
+ * earlier one is still mounted does not displace it.
+ */
+export declare class ToolRequestRegistry {
+    private readonly targets;
+    private readonly changeListeners;
+    registerTarget(target: ToolRequestTarget): () => void;
+    /**
+     * Whether a request for this tool would reach a toolbar.
+     *
+     * A surface asks before offering the affordance: a button that silently does
+     * nothing is worse than an absent one, and availability moves with policy —
+     * hence {@link onTargetsChange}.
+     */
+    canRequest(toolId: string, level?: ToolPlacementLevel): boolean;
+    /** Returns whether a target claimed the request. */
+    request(request: ToolOpenRequest): boolean;
+    /**
+     * Fires when a toolbar registers or unregisters.
+     *
+     * Not when a registered toolbar's own visible set changes: `hostsTool` is read
+     * live, so a caller re-asking `canRequest` gets the current answer. A surface
+     * that needs to notice a policy change should also follow the policy signal it
+     * already has.
+     */
+    onTargetsChange(listener: () => void): () => void;
+    /**
+     * An explicit level is a constraint; the default is a preference.
+     *
+     * Falling back off `"section"` is what lets a host place a tool at item scope only
+     * and still have a section-scoped gateway reach it. Requesting a level explicitly
+     * does not fall back, because a requester that named one meant it.
+     */
+    private findTarget;
+    private findTargetAtLevel;
+    private hostsTool;
+    private notifyChange;
+}