@pie-players/pie-assessment-toolkit 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/services/tool-context.js

@@ -31,6 +31,45 @@ function isElementContext(context) {
     return context.level === "element";
 }
 const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
+// The digit fold mirrors pie-elements-ng's response normalizer
+// (`controller-utils/src/response-normalizer.ts`), so tool visibility and
+// scoring read one number the same way. The separators fold to the
+// point-decimal marks the patterns below are written in.
+const DECIMAL_DIGIT = /\p{Nd}/u;
+const NON_ASCII_DIGITS = /(?![0-9])\p{Nd}/gu;
+// ALM, LRM, RLM, the embeddings and overrides, the isolates, and tatweel.
+const BIDI_CONTROLS_AND_TATWEEL = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069\u0640]/g;
+const digitValues = new Map();
+/**
+ * A decimal digit's value: its offset into its run of ten. Unicode assigns
+ * decimal digits only in ascending runs from zero, and runs can abut, hence the
+ * modulo.
+ */
+function digitValue(codePoint) {
+    const cached = digitValues.get(codePoint);
+    if (cached !== undefined)
+        return cached;
+    let offset = 0;
+    while (DECIMAL_DIGIT.test(String.fromCodePoint(codePoint - offset - 1))) {
+        offset += 1;
+    }
+    const value = offset % 10;
+    digitValues.set(codePoint, value);
+    return value;
+}
+/**
+ * Text with every decimal digit in ASCII, the Arabic decimal, thousands and
+ * percent signs as `.`, `,` and `%`, and bidi controls and tatweel removed, so
+ * the patterns below match `٣٫٥ × ٢ = ٧` as they match `3.5 × 2 = 7`.
+ */
+function foldNumerals(text) {
+    return text
+        .replace(BIDI_CONTROLS_AND_TATWEEL, "")
+        .replace(NON_ASCII_DIGITS, (digit) => String(digitValue(digit.codePointAt(0))))
+        .replace(/\u066B/g, ".")
+        .replace(/\u066C/g, ",")
+        .replace(/\u066A/g, "%");
+}
 /**
  * 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.
@@ -155,6 +194,10 @@ function extractContent(context, transform) {
 function extractTextContent(context) {
     return extractContent(context, stripHtml);
 }
+/** The plain text a context carries, with its numerals folded for matching. */
+function extractMatchableText(context) {
+    return foldNumerals(extractTextContent(context));
+}
 /**
  * The authored markup a context carries, tags intact.
  *
@@ -250,10 +293,24 @@ function hasSpacedSubtraction(text) {
     });
 }
 const PERCENTAGE = /\d\s*%/;
-/** A percentage taken of a number: `20% of 50`, `15% of $80`, `el 20% de 50`. */
-const PERCENTAGE_OF_NUMBER = /\d\s*%\s+(?:of|de|van)\s+[$€£]?\s?\d/i;
-/** A money amount: `$40`, `€ 12`, `12,50 €`. */
-const MONEY = /[$€£]\s?\d|\d\s?[€£]/;
+/**
+ * A percentage taken of a number: `20% of 50`, `15% of $80`, `el 20% de 50`,
+ * `٢٠٪ من ٥٠`.
+ */
+const PERCENTAGE_OF_NUMBER = /\d\s*%\s+(?:of|de|van|من)\s+\p{Sc}?\s?\d/iu;
+/** A money amount: `$40`, `€ 12`, `12,50 €`, `٥٠ ؋`. */
+const MONEY = /\p{Sc}\s?\d|\d\s?\p{Sc}/u;
+/**
+ * Currencies written as a word after the amount, by content language.
+ *
+ * Arabic writes most currencies as a word or an abbreviation where English
+ * writes a sign: `٥٠ ريالًا`, `١٢ د.إ`. English has no set, because its
+ * spelled-out "40 dollars" never counted. Script-disjoint, so every set is
+ * tried. The Arabic set is pending the native review (PIE-1364).
+ */
+const CURRENCY_WORDS = {
+    ar: /\d\s*(?:ريال|دينار|درهم|جنيه|دولار|يورو|ليرة|ر\.س|د\.إ|د\.ك|ج\.م)/u,
+};
 /**
  * Whether the text applies a percentage to a quantity.
  *
@@ -265,7 +322,10 @@ const MONEY = /[$€£]\s?\d|\d\s?[€£]/;
 function hasAppliedPercentage(text) {
     if (PERCENTAGE_OF_NUMBER.test(text))
         return true;
-    return PERCENTAGE.test(text) && MONEY.test(text);
+    if (!PERCENTAGE.test(text))
+        return false;
+    return (MONEY.test(text) ||
+        Object.values(CURRENCY_WORDS).some((pattern) => pattern.test(text)));
 }
 /**
  * Helper to check if context contains mathematical content
@@ -283,7 +343,7 @@ export function hasMathContent(context) {
     ];
     if (structuralIndicators.some((pattern) => pattern.test(markup)))
         return true;
-    const text = extractTextContent(context);
+    const text = extractMatchableText(context);
     // No bare-operator pattern: a lone hyphen or slash matches "well-known" and
     // "and/or", which would make nearly every item mathematical. An operator
     // counts only with operands around it, or when the character has no prose
@@ -399,16 +459,39 @@ export function hasSpokenContent(context) {
  * (Basic heuristic - can be overridden by tools)
  */
 export function hasScienceContent(context) {
-    const text = extractTextContent(context);
+    const text = extractMatchableText(context);
     if (hasChemicalFormula(text))
         return true;
     if (/[A-Z][a-z]?[\u2080-\u2089]/.test(text))
         return true; // Subscripted: H₂O, CO₂
-    const scienceIndicators = [
+    return Object.values(SCIENCE_KEYWORDS).some((patterns) => patterns.some((pattern) => pattern.test(text)));
+}
+/**
+ * Science vocabulary by content language, one pattern per field: chemistry,
+ * element naming, biology, physics.
+ *
+ * Every set is tried, because the sets are script-disjoint and content often
+ * declares no language: an Arabic pattern cannot match English text. A language
+ * is added as a set of its own.
+ *
+ * Arabic attaches the conjunction, prepositions and article to the word, so its
+ * patterns match stems unanchored. The exceptions are قوة (force) and طاقة
+ * (energy), bounded the way `\bforce\b` is: unbounded, بطاقة (card) and بقوة
+ * (strongly) would match. "compound" has no Arabic entry, since مركب is also a
+ * vehicle; كيميائي covers a chemical compound. The Arabic set is pending the
+ * native review (PIE-1364).
+ */
+const SCIENCE_KEYWORDS = {
+    en: [
         /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));
-}
+    ],
+    ar: [
+        /كيمياء|كيميائي|جزيء|جزيئ|جدول\s+(?:ال)?دوري/u,
+        /رمز\s+(?:ال)?عنصر/u,
+        /علم\s+الأحياء|كائن(?:ات)?\s+(?:ال)?حي|حمض\s+(?:ال)?نووي|بروتين|(?:بناء|تمثيل)\s+(?:ال)?ضوئي|(?:نظام|نظم|أنظمة)\s+(?:ال)?بيئي/u,
+        /فيزياء|فيزيائي|(?<!\p{L})(?:و|ال|وال)?(?:قوة|قوى|طاقة)(?!\p{L})|سرعة\s+(?:ال)?متجهة|تسارع|كمية\s+(?:ال)?حركة/u,
+    ],
+};

package/dist/services/tool-icons.js

@@ -25,6 +25,8 @@ const TOOL_FALLBACK_ICONS = {
     "magnifying-glass": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 14h-.79l-.28-.27A6.47 6.47 0 0 0 16 9.5 6.5 6.5 0 1 0 9.5 16a6.47 6.47 0 0 0 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5Zm-6 0A4.5 4.5 0 1 1 14 9.5 4.49 4.49 0 0 1 9.5 14ZM12 10h-2v2H9v-2H7V9h2V7h1v2h2v1Z" 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>',
+    highlighter: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M22 24H2v-4h20v4ZM13.06 5.19l3.75 3.75L7.75 18H4v-3.75l9.06-9.06Zm4.82 2.68-3.75-3.75 1.83-1.83a1 1 0 0 1 1.41 0l2.34 2.34a1 1 0 0 1 0 1.41l-1.83 1.83Z" fill="currentColor"/></svg>',
+    strikethrough: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2Zm-3.4 14L12 13.4 8.4 17 7 15.6l3.6-3.6L7 8.4 8.4 7l3.6 3.6L15.6 7 17 8.4 13.4 12l3.6 3.6-1.4 1.4Z" 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. */

package/dist/services/tool-provider-defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The provider configs a coordinator applies when the host's tools config
+ * names none for a capability.
+ *
+ * This module names capabilities on purpose, like `services/support-conflicts.ts`:
+ * a default is a statement about which capabilities a deployment starts with,
+ * which is not a decision the capability-neutral coordination layer gets to
+ * make. The coordinator applies the table without naming its entries —
+ * `check-capability-neutrality` holds it to that. These are the coordinator's
+ * previous inline defaults, moved verbatim.
+ */
+import type { ToolProvidersConfig } from "./tools-config-normalizer.js";
+export declare const DEFAULT_TOOL_PROVIDERS: ToolProvidersConfig;

package/dist/services/tool-provider-defaults.js

@@ -0,0 +1,20 @@
+/**
+ * The provider configs a coordinator applies when the host's tools config
+ * names none for a capability.
+ *
+ * This module names capabilities on purpose, like `services/support-conflicts.ts`:
+ * a default is a statement about which capabilities a deployment starts with,
+ * which is not a decision the capability-neutral coordination layer gets to
+ * make. The coordinator applies the table without naming its entries —
+ * `check-capability-neutrality` holds it to that. These are the coordinator's
+ * previous inline defaults, moved verbatim.
+ */
+export const DEFAULT_TOOL_PROVIDERS = {
+    textToSpeech: {
+        enabled: true,
+        backend: "browser",
+    },
+    annotationToolbar: {
+        enabled: true,
+    },
+};

package/dist/services/tts/browser-provider.js

@@ -4,6 +4,7 @@
  * Text-to-speech provider using the browser's Web Speech API.
  * Works in all modern browsers that support SpeechSynthesis.
  */
+import { languageTagWithoutVariants } from "@pie-players/pie-players-shared/i18n/language-tags";
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { extractSpokenText, isSsmlDocument } from "./ssml/spoken-text.js";
 import { segmentSentences as segmentTextToSentences } from "./text-segmentation.js";
@@ -383,10 +384,11 @@ class BrowserTTSProviderImpl {
      * The language of the content being read, which the toolkit sets per speak as
      * `providerOptions.contentLanguage` when the content or the host names one.
      */
+    /** The content language without variant or private-use subtags, which voices lack. */
     getContentLocale() {
         const language = this.config?.providerOptions?.contentLanguage;
         return typeof language === "string" && language.trim()
-            ? language.trim()
+            ? languageTagWithoutVariants(language)
             : undefined;
     }
     getSegmentationPolicy() {

package/dist/services/tts/tts-lifecycle.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The text-to-speech lifecycle of a `ToolkitCoordinator`: initialization from
+ * the tool config, readiness, reconfiguration, and the missing-provider report.
+ *
+ * This module is the one place in the toolkit's coordination layer allowed to
+ * name the read-aloud capability, the same way `services/tts/**` already is:
+ * the coordinator stays capability-agnostic — it hands this lifecycle the
+ * services it needs through `TtsLifecycleHost` and answers only generic
+ * questions (`ownsTool`, `isStarted`) about it — and
+ * `check-capability-neutrality` holds the coordinator to that, with one
+ * documented allowance for its public `textToSpeech`-typed config accessors.
+ *
+ * Behavior is moved, not redesigned: each method here was a private
+ * `ToolkitCoordinator` member, and the host adapters bind the same calls the
+ * members made.
+ */
+import type { AccessibilityCatalogResolver } from "../AccessibilityCatalogResolver.js";
+import type { ToolProviderConfig, ToolProvidersConfig } from "../tools-config-normalizer.js";
+import type { TTSService } from "../TTSService.js";
+import type { ToolProviderApi } from "../tool-providers/ToolProviderApi.js";
+import type { ToolRegistration } from "../ToolRegistry.js";
+/** The tool id the read-aloud capability registers under. */
+export declare const TTS_TOOL_ID = "textToSpeech";
+/**
+ * The coordinator services the TTS lifecycle runs against. The coordinator
+ * binds these once, to its own members, so its privates stay private and the
+ * seam between the generic coordinator and the capability stays explicit.
+ */
+export interface TtsLifecycleHost {
+    /** Throws `ToolkitCoordinatorDisposedError` once the coordinator is disposed. */
+    assertNotDisposed(): void;
+    /** Whether disposal has started; in-flight work stops instead of finishing. */
+    isDisposalStarted(): boolean;
+    /** Whether the error is the coordinator's own disposed signal, to rethrow. */
+    isDisposalError(error: unknown): boolean;
+    emitTelemetry(eventName: string, payload?: Record<string, unknown>): Promise<void>;
+    hooks: {
+        onBeforeTTSInit?: ((context: {
+            phase: "tts-init";
+            details: {
+                backend: string;
+            };
+        }) => void | Promise<void>) | undefined;
+        onTTSReady?: (() => void | Promise<void>) | undefined;
+    };
+    toolProviderRegistry: {
+        has(toolId: string): boolean;
+        unregister(toolId: string): Promise<void>;
+    };
+    initializeProvider(toolId: string, fallbackFollows: boolean): Promise<ToolProviderApi>;
+    ttsService: TTSService;
+    catalogResolver: AccessibilityCatalogResolver;
+    clearDegradedTool(toolId: string): void;
+    reportStartFailure(error: unknown, context: {
+        phase: "tts-init";
+    }, toolIds: Iterable<string>): void;
+    isToolGranted(toolId: string): boolean;
+    /** Whether provider initialization waits for a policy grant. */
+    lazyInit: boolean;
+    /** Whether the tool registry may still be replaced by a bound toolkit's. */
+    isToolRegistryPending(): boolean;
+    /** The validated `tools.providers` config, defaults applied. */
+    providersConfig(): ToolProvidersConfig | undefined;
+    getProviderDescriptorTools(): ToolRegistration[];
+    registerProviderFromTool(tool: ToolRegistration, replace?: boolean): Promise<void>;
+    notifyReadyChange(): void;
+}
+/** The read-aloud-specific merge in a generic tool-config update. */
+export declare function deepMergeMathSpeech(toolId: string, current: Partial<ToolProviderConfig>, updates: Partial<ToolProviderConfig>): Record<string, unknown> | undefined;
+export declare class TtsLifecycle {
+    private readonly host;
+    private initialized;
+    /** Text-to-speech failed to start and policy does not grant it. */
+    private degraded;
+    private initPromise?;
+    private reconfigurePromise?;
+    /**
+     * Whether {@link TtsLifecycle.initializeIfNeeded} has already reported a
+     * non-browser backend falling back to browser speech because no
+     * text-to-speech provider is registered. Once per coordinator: a
+     * text-to-speech config change re-runs initialization, and the missing
+     * provider is the same gap each time.
+     */
+    private reportedMissingProvider;
+    /**
+     * The backend of a fallback missing-provider report held back while the
+     * registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    private heldMissingProviderBackend;
+    constructor(host: TtsLifecycleHost);
+    get started(): boolean;
+    get failedUngranted(): boolean;
+    /** Whether `toolId` is the tool this lifecycle brings up. */
+    ownsTool(toolId: string): boolean;
+    /** Whether initialization or a reconfiguration is in flight. */
+    isStarted(): boolean;
+    /** The in-flight initialization and reconfiguration, for disposal flushes. */
+    flushInitPromises(pending: Set<Promise<unknown>>): void;
+    /**
+     * The runtime `mathSpeech` provider options for the current tool config, as
+     * the TTS service's math-speech source reads them.
+     */
+    mathSpeechRuntimeOptions(): import("./math-speech.js").SREMathSpeechOptions | undefined;
+    /**
+     * Initialize the TTS service from the `textToSpeech` tool config.
+     */
+    ensureReady(): Promise<void>;
+    private waitForPendingReconfigure;
+    private initializeIfNeeded;
+    private resolveToolConfig;
+    private initializeService;
+    private reportMissingProvider;
+    /**
+     * Report a missing-provider report held back while the registry was
+     * unsettled, now that the registry has settled without one.
+     */
+    reportHeldMissingProvider(): void;
+    /**
+     * Drop a held missing-provider report without reporting it: a real registry
+     * settled, so the stale gap never applied.
+     */
+    discardHeldMissingProvider(): void;
+    /**
+     * Readiness waits for text-to-speech when it is enabled and either starts
+     * eagerly or is granted: a granted read-aloud fails before the learner starts.
+     */
+    requiredForReadiness(): boolean;
+    /**
+     * Starts text-to-speech for readiness. A failure policy does not grant leaves
+     * the tool degraded, reporting itself unavailable, and readiness settles; a
+     * granted tool's failure rejects.
+     */
+    startForReadiness(): Promise<void>;
+    /**
+     * Re-register the text-to-speech provider for the current config and registry,
+     * then re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after the
+     * reset.
+     */
+    scheduleReconfigure(): void;
+    private reconfigure;
+}