@sabiq/utils 0.0.1

package/dist/cjs/utils/validation.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRecitation = exports.defaultThreshold = void 0;
+const levenshtein_1 = require("./levenshtein");
+const arabic_1 = require("./arabic");
+const wordAlternatives_1 = require("./wordAlternatives");
+/**
+ * Standard threshold: 30% of the word's length, rounded up.
+ */
+function defaultThreshold(word) {
+    return Math.ceil(word.length * 0.3);
+}
+exports.defaultThreshold = defaultThreshold;
+function isBetterAsMerge(prevSpoken, currentSpoken, prevExpected, currentExpected) {
+    const currNorm = joinForAltCompare(currentSpoken);
+    if (currNorm.length === 0 || currNorm.length > 3)
+        return false;
+    const prevNorm = joinForAltCompare(prevSpoken);
+    const expPrevNorm = joinForAltCompare(prevExpected);
+    const expCurrNorm = joinForAltCompare(currentExpected);
+    if (prevNorm.length === 0 ||
+        expPrevNorm.length === 0 ||
+        expCurrNorm.length === 0) {
+        return false;
+    }
+    const allowedPrev = defaultThreshold(expPrevNorm);
+    const mergedLen = prevNorm.length + currNorm.length;
+    if (mergedLen > expPrevNorm.length + allowedPrev)
+        return false;
+    if (expPrevNorm.length > mergedLen + allowedPrev)
+        return false;
+    const dPrev = (0, levenshtein_1.levenshteinDistance)(prevNorm, expPrevNorm);
+    if (dPrev === 0)
+        return false;
+    const merged = prevNorm + currNorm;
+    const dMerged = (0, levenshtein_1.levenshteinDistance)(merged, expPrevNorm);
+    if (dMerged > allowedPrev || dMerged >= dPrev)
+        return false;
+    // Tiebreaker: only override CORRECT if merge fits prev STRICTLY better
+    // than current fits its own expected. Without this, a coincidentally
+    // similar current (e.g. "في" sharing a leading char with "ني" in "مكني")
+    // would falsely get absorbed.
+    const dCurrent = (0, levenshtein_1.levenshteinDistance)(currNorm, expCurrNorm);
+    return dMerged < dCurrent;
+}
+function matchesMain(spoken, expected) {
+    const a = (0, arabic_1.normalizeArabic)(spoken);
+    const b = (0, arabic_1.normalizeArabic)(expected);
+    return (0, levenshtein_1.levenshteinDistance)(a, b) <= defaultThreshold(b);
+}
+function isPrefixOfMain(spoken, expected) {
+    const a = (0, arabic_1.normalizeArabic)(spoken);
+    const b = (0, arabic_1.normalizeArabic)(expected);
+    if (a.length === 0 || a.length >= b.length)
+        return false;
+    const prefix = b.slice(0, a.length);
+    return (0, levenshtein_1.levenshteinDistance)(a, prefix) <= defaultThreshold(prefix);
+}
+function joinForAltCompare(s) {
+    return (0, arabic_1.normalizeArabic)(s).replace(/[\s\u200B-\u200F\u202A-\u202E\u00A0]/g, "");
+}
+function matchesAnyAlternative(spoken, alts) {
+    const a = joinForAltCompare(spoken);
+    for (const alt of alts) {
+        const altNorm = joinForAltCompare(alt);
+        const distance = (0, levenshtein_1.levenshteinDistance)(a, altNorm);
+        const allowed = defaultThreshold(altNorm);
+        const lenDiff = Math.abs(a.length - altNorm.length);
+        // For short joined alts (≤ 4 chars — the compact muqatta'at forms),
+        // require exact equality. Each char in a compact form represents one
+        // entire letter of the muqatta'at, so even a single edit completely
+        // changes the meaning. Without this, a single spoken letter like "الف"
+        // (3 chars) falsely full-matches the compact alt "الم" (3 chars, also
+        // 1 edit away), preventing the prefix path from collecting subsequent
+        // letters.
+        if (altNorm.length <= 4) {
+            if (distance === 0)
+                return true;
+            continue;
+        }
+        if (distance <= allowed && lenDiff <= Math.ceil(allowed / 2)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isPrefixOfAnyAlternative(spoken, alts) {
+    const a = joinForAltCompare(spoken);
+    if (a.length === 0)
+        return false;
+    for (const alt of alts) {
+        const altNorm = joinForAltCompare(alt);
+        if (a.length >= altNorm.length)
+            continue;
+        const prefix = altNorm.slice(0, a.length);
+        if ((0, levenshtein_1.levenshteinDistance)(a, prefix) <= defaultThreshold(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Inverse of isPrefixOfMain: is the EXPECTED word a prefix of SPOKEN?
+ * Detects when STT combined two mushaf words into one token.
+ */
+function isContainedIn(spoken, expected) {
+    const a = (0, arabic_1.normalizeArabic)(spoken);
+    const b = (0, arabic_1.normalizeArabic)(expected);
+    if (b.length < 2)
+        return false;
+    if (b.length >= a.length)
+        return false;
+    const remainderLen = a.length - b.length;
+    if (remainderLen < 2)
+        return false;
+    const prefix = a.slice(0, b.length);
+    // First-character anchor. The single most reliable signal that prefix
+    // is structurally aligned with expected, not coincidentally similar.
+    if (prefix[0] !== b[0])
+        return false;
+    return (0, levenshtein_1.levenshteinDistance)(prefix, b) <= defaultThreshold(b);
+}
+function splitContained(spoken, expected) {
+    const a = (0, arabic_1.normalizeArabic)(spoken);
+    const b = (0, arabic_1.normalizeArabic)(expected);
+    return a.slice(b.length);
+}
+/**
+ * Word-split merge detection.
+ *
+ * STT sometimes splits one mushaf word into two short tokens (e.g. "يَٰذَا"
+ * → "يا" + "ذا"). The first token may have been accepted as a fuzzy match
+ * for the mushaf word; the second now has nothing to match against.
+ *
+ * We detect this by checking whether `prevSpoken + currentSpoken` matches
+ * the previous expected word *strictly better* than `prevSpoken` alone.
+ *
+ * The strictness gate (dMerged < dPrev) is critical:
+ *   - If prev was an exact match (dPrev = 0), no merge is possible — current
+ *     must be a separate word.
+ *   - If prev was fuzzy (dPrev > 0), merge fires only when adding current
+ *     improves the distance, which is exactly the STT-split signal.
+ */
+function matchesAsMerge(prevSpoken, currentSpoken, prevExpected) {
+    const prevNorm = joinForAltCompare(prevSpoken);
+    const currNorm = joinForAltCompare(currentSpoken);
+    const expNorm = joinForAltCompare(prevExpected);
+    if (prevNorm.length === 0 || currNorm.length === 0 || expNorm.length === 0) {
+        return false;
+    }
+    if (currNorm.length > expNorm.length) {
+        return false;
+    }
+    const allowed = defaultThreshold(expNorm);
+    const mergedLen = prevNorm.length + currNorm.length;
+    // Length-difference lower bound on Levenshtein. If merged is too far
+    // from expected in raw length, distance can't be within threshold.
+    if (mergedLen > expNorm.length + allowed)
+        return false;
+    if (expNorm.length > mergedLen + allowed)
+        return false;
+    const merged = prevNorm + currNorm;
+    const dMerged = (0, levenshtein_1.levenshteinDistance)(merged, expNorm);
+    if (dMerged > allowed)
+        return false;
+    const dPrev = (0, levenshtein_1.levenshteinDistance)(prevNorm, expNorm);
+    // Improvement gate: merged must be strictly closer, OR same distance
+    // with strictly more length (which means current contributed signal
+    // that aligned with the tail of expected).
+    return dMerged < dPrev || (dMerged === dPrev && mergedLen > prevNorm.length);
+}
+/**
+ * Validate a buffered spoken token against the expected word at currentIndex.
+ *
+ * @param lastCorrectToken The raw token that produced the most recent
+ *        "correct" outcome at currentIndex - 1. Used by the merge mechanism
+ *        to detect STT word-splits. Pass null if not tracking, or if the
+ *        previous outcome was anything other than "correct".
+ */
+function validateRecitation(buffer, expected, currentIndex, alternatives = wordAlternatives_1.wordAlternatives, lastCorrectToken = null) {
+    const trimmed = buffer.trim();
+    const target = expected[currentIndex];
+    if (!target) {
+        return { status: "wrong", advance: true, newBuffer: "" };
+    }
+    const position = { surah: target.surah, verse: target.verse };
+    const alts = (0, wordAlternatives_1.getAlternativesFor)(target.text, position.surah, position.verse, alternatives);
+    const tryMerge = () => {
+        if (!lastCorrectToken || currentIndex === 0)
+            return null;
+        const prevExpected = expected[currentIndex - 1];
+        if (!prevExpected)
+            return null;
+        if (matchesAsMerge(lastCorrectToken, trimmed, prevExpected.text)) {
+            return { status: "merge", advance: false, newBuffer: "" };
+        }
+        return null;
+    };
+    // === Muqatta'at path ===
+    if (alts.length > 0) {
+        if (matchesAnyAlternative(trimmed, alts)) {
+            return { status: "correct", advance: true, newBuffer: "" };
+        }
+        if ((0, arabic_1.normalizeArabic)(trimmed) === (0, arabic_1.normalizeArabic)(target.text)) {
+            return { status: "correct", advance: true, newBuffer: "" };
+        }
+        if (isPrefixOfAnyAlternative(trimmed, alts)) {
+            return { status: "pending", advance: false, newBuffer: trimmed };
+        }
+        const merge = tryMerge();
+        if (merge)
+            return merge;
+        return { status: "wrong", advance: true, newBuffer: "" };
+    }
+    // === Normal main-word path ===
+    if (matchesMain(trimmed, target.text)) {
+        if (lastCorrectToken && currentIndex > 0) {
+            const prevExpected = expected[currentIndex - 1];
+            if (prevExpected &&
+                isBetterAsMerge(lastCorrectToken, trimmed, prevExpected.text, target.text)) {
+                return { status: "merge", advance: false, newBuffer: "" };
+            }
+        }
+        return { status: "correct", advance: true, newBuffer: "" };
+    }
+    if (isContainedIn(trimmed, target.text)) {
+        return {
+            status: "split",
+            advance: true,
+            newBuffer: "",
+            remainder: splitContained(trimmed, target.text),
+        };
+    }
+    if (isPrefixOfMain(trimmed, target.text)) {
+        return { status: "pending", advance: false, newBuffer: trimmed };
+    }
+    const merge = tryMerge();
+    if (merge)
+        return merge;
+    return { status: "wrong", advance: true, newBuffer: "" };
+}
+exports.validateRecitation = validateRecitation;

package/dist/cjs/utils/wordAlternatives.d.ts

@@ -0,0 +1,41 @@
+export interface WordAlternative {
+    /** The expected word in the mushaf (or its normalized form). */
+    word: string;
+    /** Acceptable spoken alternatives. */
+    alternatives: string[];
+    /** Optional scope: only apply at this surah:verse. */
+    scope?: {
+        surah: number;
+        verse: number;
+    };
+}
+/**
+ * The الحروف المقطعة (muqatta'at) appear ONLY at ayah 1 of specific surahs
+ * (and in one case, ayah 2 of الشورى — عسق). They look identical to normal
+ * Arabic words like أَلَمْ in other contexts, so we must scope them.
+ *
+ * Each muqatta'at entry carries up to three alt forms, listed in order of
+ * expected real-world frequency. Whichever matches first wins, so order
+ * matters for performance only — correctness is unaffected by ordering.
+ *
+ *   1. Realistic hybrid — short letters compact (ك, ه, ط, ح, ر), long
+ *      letters spelled out (ميم, لام, سين, عين, صاد, قاف, نون, كاف).
+ *      This is what reciters actually say, and what STT actually delivers.
+ *
+ *   2. Pure compact — every letter as a single consonant char. After
+ *      joinForAltCompare strips spaces this becomes the mushaf form
+ *      itself, giving exact prefix matching for letter-by-letter input.
+ *
+ *   3. Full letter names — every letter spelled out (الف, ها, يا, etc.).
+ *      Backstop for STT that delivers full phonetic forms.
+ *
+ * Single-letter muqatta'at (ص، ق، ن) only need two forms since compact
+ * and mushaf collapse to the same single character.
+ */
+export declare const wordAlternatives: WordAlternative[];
+/**
+ * Look up alternatives for an expected word at a specific position.
+ * Returns alternatives only if a scoped entry matches the surah:verse,
+ * or if there's an unscoped entry (for future generic alternatives).
+ */
+export declare function getAlternativesFor(expected: string, surah: number, verse: number, alternatives?: WordAlternative[]): string[];

package/dist/cjs/utils/wordAlternatives.js

@@ -0,0 +1,230 @@
+"use strict";
+// utils/wordAlternatives.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAlternativesFor = exports.wordAlternatives = void 0;
+const arabic_1 = require("./arabic");
+/**
+ * The الحروف المقطعة (muqatta'at) appear ONLY at ayah 1 of specific surahs
+ * (and in one case, ayah 2 of الشورى — عسق). They look identical to normal
+ * Arabic words like أَلَمْ in other contexts, so we must scope them.
+ *
+ * Each muqatta'at entry carries up to three alt forms, listed in order of
+ * expected real-world frequency. Whichever matches first wins, so order
+ * matters for performance only — correctness is unaffected by ordering.
+ *
+ *   1. Realistic hybrid — short letters compact (ك, ه, ط, ح, ر), long
+ *      letters spelled out (ميم, لام, سين, عين, صاد, قاف, نون, كاف).
+ *      This is what reciters actually say, and what STT actually delivers.
+ *
+ *   2. Pure compact — every letter as a single consonant char. After
+ *      joinForAltCompare strips spaces this becomes the mushaf form
+ *      itself, giving exact prefix matching for letter-by-letter input.
+ *
+ *   3. Full letter names — every letter spelled out (الف, ها, يا, etc.).
+ *      Backstop for STT that delivers full phonetic forms.
+ *
+ * Single-letter muqatta'at (ص، ق، ن) only need two forms since compact
+ * and mushaf collapse to the same single character.
+ */
+exports.wordAlternatives = [
+    // البقرة 2:1, آل عمران 3:1, العنكبوت 29:1, الروم 30:1, لقمان 31:1, السجدة 32:1
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 2, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 3, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 29, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 30, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 31, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 32, verse: 1 },
+    },
+    // الأعراف 7:1
+    {
+        word: "المص",
+        alternatives: ["ا لام ميم صاد", "ا ل م ص", "الف لام ميم صاد"],
+        scope: { surah: 7, verse: 1 },
+    },
+    // يونس 10:1, هود 11:1, يوسف 12:1, إبراهيم 14:1, الحجر 15:1
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 10, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 11, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 12, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 14, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 15, verse: 1 },
+    },
+    // الرعد 13:1
+    {
+        word: "المر",
+        alternatives: [
+            "ا لام ميم را",
+            "ا ل م ر",
+            "الف لام ميم را",
+            "الف لام ميم راء",
+        ],
+        scope: { surah: 13, verse: 1 },
+    },
+    // مريم 19:1
+    {
+        word: "كهيعص",
+        alternatives: [
+            "ك ه يا عين صاد",
+            "ك ه ي ع ص",
+            "كاف ها يا عين صاد",
+            "كاف هاء ياء عين صاد",
+        ],
+        scope: { surah: 19, verse: 1 },
+    },
+    // طه 20:1
+    {
+        word: "طه",
+        alternatives: ["ط ها", "ط ه", "طا ها", "طا هاء"],
+        scope: { surah: 20, verse: 1 },
+    },
+    // الشعراء 26:1, القصص 28:1
+    {
+        word: "طسم",
+        alternatives: ["ط سين ميم", "ط س م", "طا سين ميم"],
+        scope: { surah: 26, verse: 1 },
+    },
+    {
+        word: "طسم",
+        alternatives: ["ط سين ميم", "ط س م", "طا سين ميم"],
+        scope: { surah: 28, verse: 1 },
+    },
+    // النمل 27:1
+    {
+        word: "طس",
+        alternatives: ["ط سين", "ط س", "طا سين"],
+        scope: { surah: 27, verse: 1 },
+    },
+    // يس 36:1 — realistic and full collapse to "يا سين"; ياسين covers the
+    // run-on form some reciters/STT produce.
+    {
+        word: "يس",
+        alternatives: ["يا سين", "ي س", "ياسين"],
+        scope: { surah: 36, verse: 1 },
+    },
+    // ص 38:1 — single letter; compact and mushaf form are identical.
+    {
+        word: "ص",
+        alternatives: ["صاد", "ص"],
+        scope: { surah: 38, verse: 1 },
+    },
+    // غافر 40:1, فصلت 41:1, الزخرف 43:1, الدخان 44:1, الجاثية 45:1, الأحقاف 46:1
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 40, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 41, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 43, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 44, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 45, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 46, verse: 1 },
+    },
+    // الشورى 42:1 = حم, 42:2 = عسق (split across two ayahs)
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 42, verse: 1 },
+    },
+    {
+        word: "عسق",
+        alternatives: ["عين سين قاف", "ع س ق"],
+        scope: { surah: 42, verse: 2 },
+    },
+    // ق 50:1 — single letter; compact and mushaf collapse.
+    {
+        word: "ق",
+        alternatives: ["قاف", "ق"],
+        scope: { surah: 50, verse: 1 },
+    },
+    // القلم 68:1 — single letter; compact and mushaf collapse.
+    {
+        word: "ن",
+        alternatives: ["نون", "ن"],
+        scope: { surah: 68, verse: 1 },
+    },
+];
+/**
+ * Look up alternatives for an expected word at a specific position.
+ * Returns alternatives only if a scoped entry matches the surah:verse,
+ * or if there's an unscoped entry (for future generic alternatives).
+ */
+function getAlternativesFor(expected, surah, verse, alternatives = exports.wordAlternatives) {
+    const normalized = (0, arabic_1.normalizeArabic)(expected);
+    const out = [];
+    for (const entry of alternatives) {
+        const wordMatches = entry.word === expected || entry.word === normalized;
+        if (!wordMatches)
+            continue;
+        // Unscoped entries always apply.
+        if (!entry.scope) {
+            out.push(...entry.alternatives);
+            continue;
+        }
+        // Scoped entries only apply at their position.
+        if (entry.scope.surah === surah && entry.scope.verse === verse) {
+            out.push(...entry.alternatives);
+        }
+    }
+    return out;
+}
+exports.getAlternativesFor = getAlternativesFor;

package/dist/esm/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './useRecitationValidator';

package/dist/esm/hooks/index.js

@@ -0,0 +1 @@
+export * from './useRecitationValidator';

package/dist/esm/hooks/useRecitationValidator.d.ts

@@ -0,0 +1,25 @@
+import { WordAlternative } from "../utils/wordAlternatives";
+export interface ExpectedWord {
+    text: string;
+    key: string;
+    surah: number;
+    verse: number;
+}
+type WordStatus = "correct" | "wrong" | "skipped" | "current";
+export declare function useRecitationValidator(expectedWords: ExpectedWord[], alternatives?: WordAlternative[]): {
+    currentIndex: number;
+    buffer: string;
+    interim: string;
+    wordHighlights: Map<string, WordStatus>;
+    ingestFinal: (transcript: string) => void;
+    ingestInterim: (transcript: string) => void;
+    reset: () => void;
+    jumpTo: (i: number) => void;
+    reAnchor: () => void;
+    isComplete: boolean;
+    /** True while the engine is searching for the user's position.
+     *  Toggles to false on successful anchor, true again on wrong-outcome
+     *  or `reAnchor()` call. */
+    isAnchoring: boolean;
+};
+export {};