@sabiq/utils 0.0.1

package/dist/esm/hooks/useRecitationValidator.js

@@ -0,0 +1,388 @@
+import { useCallback, useMemo, useReducer, useState } from "react";
+import { defaultThreshold, validateRecitation, } from "../utils/validation";
+import { getAlternativesFor, wordAlternatives, } from "../utils/wordAlternatives";
+import { levenshteinDistance } from "../utils/levenshtein";
+import { normalizeArabic } from "../utils/arabic";
+/** Maximum recursion depth for split-driven re-processing. */
+const SPLIT_DEPTH_LIMIT = 5;
+/* ------------------------------------------------------------------ */
+/*  Anchor detection                                                  */
+/* ------------------------------------------------------------------ */
+/** Minimum tokens we need before attempting position-finding. Below this
+ *  the buffer just holds. Single-token anchoring is too easy to fool. */
+const MIN_ANCHOR_TOKENS = 2;
+/** Required count of consecutive matching expected-words from a candidate
+ *  position. Two is the practical floor — common short words match
+ *  everywhere, so we need at least a pair of aligned hits. */
+const MIN_ANCHOR_CONSECUTIVE = 2;
+/** Required total normalized-character length of the matched run.
+ *  Filters out "في ما"-style runs of two very short words coincidentally
+ *  matching in multiple page locations. */
+const MIN_ANCHOR_TOTAL_SCORE = 6;
+/** Cap on how many recent tokens we keep buffered while searching.
+ *  Older tokens slide off so an unanchored session doesn't grow without
+ *  bound. Also defines the point at which we stop deferring ambiguous
+ *  ties and just commit to the first candidate. */
+const MAX_ANCHOR_BUFFER = 8;
+/** Re-anchor (mid-recitation) search radius. After the very first anchor
+ *  has been found, subsequent re-anchors limit their scan to this many
+ *  positions ahead of currentIndex. This prevents the dreaded backward
+ *  jump (which would behave like the removed "rewind" feature) and also
+ *  keeps the scan cheap once we know roughly where the user is. */
+const SEARCH_FORWARD_WINDOW = 10;
+/**
+ * Find the best position in `expected[searchStart, searchEnd)` where the
+ * buffered tokens align as a consecutive run.
+ *
+ * Returns null if no candidate clears the thresholds, OR if the top score
+ * is tied across multiple positions and we still have room in the buffer
+ * to wait for a disambiguating token.
+ *
+ * Reuses validateRecitation per (token, position) probe so muqatta'at
+ * and verse-scoped alternatives are honored during anchor detection too.
+ */
+function findAnchor(tokens, expected, alternatives, searchStart, searchEnd) {
+    if (tokens.length < MIN_ANCHOR_TOKENS)
+        return null;
+    if (searchStart >= searchEnd)
+        return null;
+    const candidates = [];
+    for (let i = searchStart; i < searchEnd; i++) {
+        let consecutive = 0;
+        let score = 0;
+        for (let j = 0; j < tokens.length && i + j < expected.length; j++) {
+            const res = validateRecitation(tokens[j], expected, i + j, alternatives, null);
+            if (res.status === "correct" || res.status === "split") {
+                consecutive++;
+                score += normalizeArabic(expected[i + j].text).length;
+            }
+            else {
+                break;
+            }
+        }
+        if (consecutive >= MIN_ANCHOR_CONSECUTIVE &&
+            score >= MIN_ANCHOR_TOTAL_SCORE) {
+            candidates.push({ index: i, matchedCount: consecutive, score });
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => b.score - a.score || a.index - b.index);
+    const top = candidates[0];
+    // Ambiguity defer: multiple positions tied at top? Wait for another
+    // token unless the buffer is already at capacity.
+    const tied = candidates.filter((c) => c.score === top.score);
+    if (tied.length > 1 && tokens.length < MAX_ANCHOR_BUFFER) {
+        return null;
+    }
+    return top;
+}
+/* ------------------------------------------------------------------ */
+/*  Logging                                                           */
+/* ------------------------------------------------------------------ */
+function logDecision(spoken, target, result, alts) {
+    const icon = result.status === "wrong"
+        ? "❌"
+        : result.status === "split"
+            ? "✂️"
+            : result.status === "merge"
+                ? "🔗"
+                : "";
+    const color = result.status === "wrong"
+        ? "#d33"
+        : result.status === "split"
+            ? "#a60"
+            : result.status === "merge"
+                ? "#060"
+                : "green";
+    const headerSuffix = result.status === "split"
+        ? ` → split, remainder "${result.remainder}"`
+        : result.status === "merge"
+            ? ` → merged with previous`
+            : "";
+    console.groupCollapsed(`%c${icon} ${result.status.toUpperCase()} at ${target.surah}:${target.verse} (key ${target.key}) — "${spoken}" vs "${target.text}"${headerSuffix}`, `color: ${color}; font-weight: bold;`);
+    const spokenNorm = normalizeArabic(spoken);
+    const expectedNorm = normalizeArabic(target.text);
+    console.log(`Expected: "${target.text}" → norm "${expectedNorm}" (${expectedNorm.length} chars)`);
+    console.log(`Spoken:   "${spoken}" → norm "${spokenNorm}" (${spokenNorm.length} chars)`);
+    const mainDist = levenshteinDistance(spokenNorm, expectedNorm);
+    const mainAllowed = defaultThreshold(expectedNorm);
+    console.log(`MAIN: distance ${mainDist} / allowed ${mainAllowed} → ${mainDist <= mainAllowed ? "✓ MATCH" : "✗"}`);
+    if (alts.length === 0) {
+        console.log("ALTERNATIVES: none in scope");
+    }
+    else {
+        console.log(`ALTERNATIVES (${alts.length} in scope):`);
+        for (const alt of alts) {
+            const altNorm = normalizeArabic(alt);
+            const aDist = levenshteinDistance(spokenNorm, altNorm);
+            const aAllowed = defaultThreshold(altNorm);
+            console.log(`  • "${alt}" → norm "${altNorm}", distance ${aDist} / allowed ${aAllowed} → ${aDist <= aAllowed ? "✓ MATCH" : "✗"}`);
+        }
+    }
+    console.log(`→ verdict: ${result.status}, advance: ${result.advance}, newBuffer: "${result.newBuffer}"${result.remainder != null ? `, remainder: "${result.remainder}"` : ""}`);
+    console.groupEnd();
+}
+const initial = {
+    currentIndex: 0,
+    buffer: "",
+    statuses: new Map(),
+    lastCorrectToken: null,
+    anchorPending: true,
+    anchorTokens: [],
+};
+/* ------------------------------------------------------------------ */
+/*  Token processing                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Process one token. Returns the new committed state.
+ *
+ * Status handling:
+ *   - pending: hold the buffer, don't advance
+ *   - split:   consume prefix as current word, advance, recursively re-process
+ *              the remainder (capped by SPLIT_DEPTH_LIMIT)
+ *   - merge:   token consumed as continuation of previous correct word;
+ *              cursor unchanged, lastCorrectToken extended for chained merges
+ *   - correct: mark and advance, update lastCorrectToken
+ *   - wrong:   mark, advance, clear lastCorrectToken, AND flip anchorPending
+ *              true so the next token re-syncs to where the user actually is
+ */
+function processToken(state, token, expected, alternatives, splitDepth = 0) {
+    if (state.currentIndex >= expected.length)
+        return state;
+    const target = expected[state.currentIndex];
+    const newBuffer = state.buffer ? `${state.buffer} ${token}` : token;
+    const result = validateRecitation(newBuffer, expected, state.currentIndex, alternatives, state.lastCorrectToken);
+    const altsInScope = getAlternativesFor(target.text, target.surah, target.verse, alternatives);
+    logDecision(newBuffer, target, result, altsInScope);
+    if (result.status === "pending") {
+        return Object.assign(Object.assign({}, state), { buffer: result.newBuffer });
+    }
+    if (result.status === "merge") {
+        const prevWord = expected[state.currentIndex - 1];
+        console.log(`%c🔗 MERGE at idx ${state.currentIndex}: "${state.lastCorrectToken}" + "${newBuffer}" completes prev word "${prevWord === null || prevWord === void 0 ? void 0 : prevWord.text}" — token consumed without advance`, "background: #efe; color: #060; padding: 2px 6px; font-weight: bold;");
+        return Object.assign(Object.assign({}, state), { buffer: "", lastCorrectToken: state.lastCorrectToken
+                ? `${state.lastCorrectToken} ${newBuffer}`
+                : newBuffer });
+    }
+    if (result.status === "split" && result.remainder != null) {
+        if (splitDepth >= SPLIT_DEPTH_LIMIT) {
+            console.warn(`%c⚠ split depth limit hit at idx ${state.currentIndex} — treating as wrong`, "color: #c80;");
+            const nextStatuses = new Map(state.statuses);
+            nextStatuses.set(target.key, "wrong");
+            console.log(`%c⟳ RE-ANCHOR triggered after wrong at idx ${state.currentIndex} (split-depth) — forward window from idx ${state.currentIndex + 1}`, "background: #fef5e0; color: #a60; padding: 2px 6px; font-weight: bold;");
+            return Object.assign(Object.assign({}, state), { currentIndex: state.currentIndex + 1, buffer: "", statuses: nextStatuses, lastCorrectToken: null, anchorPending: true, anchorTokens: [] });
+        }
+        const nextStatuses = new Map(state.statuses);
+        nextStatuses.set(target.key, "correct");
+        console.log(`%c✂️ SPLIT at idx ${state.currentIndex}: consumed "${target.text}", remainder "${result.remainder}" → next slot`, "background: #fef5e0; color: #a60; padding: 2px 6px; font-weight: bold;");
+        const advancedState = Object.assign(Object.assign({}, state), { currentIndex: state.currentIndex + 1, buffer: "", statuses: nextStatuses, lastCorrectToken: null });
+        return processToken(advancedState, result.remainder, expected, alternatives, splitDepth + 1);
+    }
+    // correct or wrong
+    const nextStatuses = new Map(state.statuses);
+    nextStatuses.set(target.key, result.status);
+    const advanced = result.advance ? state.currentIndex + 1 : state.currentIndex;
+    if (result.status === "wrong") {
+        // Auto re-anchor: STT may have mis-aligned us. Let the next 1–2 tokens
+        // resync to where the user actually is via the forward-windowed search.
+        console.log(`%c⟳ RE-ANCHOR triggered after wrong at idx ${state.currentIndex} — forward window from idx ${advanced}`, "background: #fef5e0; color: #a60; padding: 2px 6px; font-weight: bold;");
+        return Object.assign(Object.assign({}, state), { currentIndex: advanced, buffer: "", statuses: nextStatuses, lastCorrectToken: null, anchorPending: true, anchorTokens: [] });
+    }
+    return Object.assign(Object.assign({}, state), { currentIndex: advanced, buffer: "", statuses: nextStatuses, lastCorrectToken: result.status === "correct" ? newBuffer : null });
+}
+/**
+ * Entry point for one spoken token. Routes through anchor detection if
+ * we haven't locked the user's start position yet (or have re-entered
+ * anchor mode after silence / wrong), otherwise straight to per-target
+ * validation.
+ *
+ * Search strategy:
+ *   - currentIndex === 0  → whole page (fresh start, no prior position
+ *     to anchor relative to).
+ *   - currentIndex > 0    → two phases:
+ *       1) Forward window [currentIndex, currentIndex + SEARCH_FORWARD_WINDOW).
+ *          Prefers the cascade-recovery case (continuous reciting with an
+ *          STT glitch). Fast and prevents tiny errors from throwing us
+ *          back to an earlier verse.
+ *       2) If forward returns null, fall back to the whole page. Handles
+ *          legitimate restart-from-elsewhere (silence then back-to-top,
+ *          jump to a different verse, etc). Backward jumps land here, and
+ *          the same anchor thresholds (2+ consecutive, 6+ char score,
+ *          ambiguity defer) still gate them.
+ */
+function ingestToken(state, token, expected, alternatives) {
+    if (!state.anchorPending) {
+        return processToken(state, token, expected, alternatives);
+    }
+    let buffered = [...state.anchorTokens, token];
+    if (buffered.length > MAX_ANCHOR_BUFFER) {
+        buffered = buffered.slice(-MAX_ANCHOR_BUFFER);
+    }
+    const isFreshStart = state.currentIndex === 0;
+    let anchor = null;
+    let scopeLabel;
+    if (isFreshStart) {
+        anchor = findAnchor(buffered, expected, alternatives, 0, expected.length);
+        scopeLabel = "whole page (fresh start)";
+    }
+    else {
+        // Phase 1: forward window
+        const fwdEnd = Math.min(expected.length, state.currentIndex + SEARCH_FORWARD_WINDOW);
+        anchor = findAnchor(buffered, expected, alternatives, state.currentIndex, fwdEnd);
+        if (anchor !== null) {
+            scopeLabel = `forward [${state.currentIndex}, ${fwdEnd})`;
+        }
+        else {
+            // Phase 2: whole-page fallback (covers backward restarts, jumps
+            // to different sections, etc — any position outside the forward
+            // window that the user might actually be reciting from).
+            anchor = findAnchor(buffered, expected, alternatives, 0, expected.length);
+            scopeLabel = anchor
+                ? "whole page (forward exhausted)"
+                : `forward [${state.currentIndex}, ${fwdEnd}) → whole page, both empty`;
+        }
+    }
+    if (anchor === null) {
+        console.log(`%c⚓ ANCHORING (${scopeLabel}) — ${buffered.length} token${buffered.length === 1 ? "" : "s"} buffered ("${buffered.join(" ")}") — no confident match yet`, "color: #999; font-style: italic;");
+        return Object.assign(Object.assign({}, state), { anchorTokens: buffered });
+    }
+    const at = expected[anchor.index];
+    const direction = !isFreshStart && anchor.index < state.currentIndex
+        ? " ⤺ BACKWARD"
+        : !isFreshStart &&
+            anchor.index > state.currentIndex + SEARCH_FORWARD_WINDOW - 1
+            ? " ⤻ DISTANT-FORWARD"
+            : "";
+    console.log(`%c⚓ ANCHOR FOUND${direction} at idx ${anchor.index} (${at.surah}:${at.verse}, "${at.text}") via ${scopeLabel} — matched ${anchor.matchedCount} word${anchor.matchedCount === 1 ? "" : "s"}, score ${anchor.score} — replaying ${buffered.length} buffered token${buffered.length === 1 ? "" : "s"}`, "background: #e7f3ff; color: #06a; padding: 2px 6px; font-weight: bold;");
+    // If the anchor jumped FORWARD past one or more positions (cascade
+    // recovery, or initial mid-page start), mark those intermediate words
+    // as "skipped" so they render distinctly (gray) instead of looking
+    // unrecited. Existing statuses are preserved — a word previously
+    // marked wrong stays wrong, a word marked correct stays correct.
+    let nextStatuses = state.statuses;
+    if (anchor.index > state.currentIndex) {
+        const updated = new Map(state.statuses);
+        let skippedCount = 0;
+        for (let i = state.currentIndex; i < anchor.index; i++) {
+            const key = expected[i].key;
+            if (!updated.has(key)) {
+                updated.set(key, "skipped");
+                skippedCount++;
+            }
+        }
+        if (skippedCount > 0) {
+            console.log(`%c⏭ SKIPPED ${skippedCount} word${skippedCount === 1 ? "" : "s"} at indices [${state.currentIndex}, ${anchor.index}) — marked "skipped"`, "color: #888; font-weight: bold;");
+            nextStatuses = updated;
+        }
+    }
+    let nextState = {
+        currentIndex: anchor.index,
+        buffer: "",
+        statuses: nextStatuses,
+        lastCorrectToken: null,
+        anchorPending: false,
+        anchorTokens: [],
+    };
+    for (const t of buffered) {
+        nextState = processToken(nextState, t, expected, alternatives);
+    }
+    return nextState;
+}
+function replay(start, transcript, expected, alternatives) {
+    const tokens = transcript.trim().split(/\s+/).filter(Boolean);
+    let state = start;
+    for (const token of tokens) {
+        state = ingestToken(state, token, expected, alternatives);
+    }
+    return state;
+}
+/* ------------------------------------------------------------------ */
+/*  Reducer                                                           */
+/* ------------------------------------------------------------------ */
+function reducer(state, action) {
+    switch (action.type) {
+        case "RESET":
+            return {
+                currentIndex: 0,
+                buffer: "",
+                statuses: new Map(),
+                lastCorrectToken: null,
+                anchorPending: true,
+                anchorTokens: [],
+            };
+        case "JUMP_TO":
+            return Object.assign(Object.assign({}, state), { currentIndex: action.index, buffer: "", lastCorrectToken: null, anchorPending: false, anchorTokens: [] });
+        case "RE_ANCHOR":
+            // No-op if we're already anchoring — just clear any half-collected
+            // tokens so the new pass starts fresh.
+            console.log(`%c⟳ RE-ANCHOR requested (silence/error) at idx ${state.currentIndex}${state.anchorPending ? " — already anchoring, clearing buffer" : ""}`, "background: #fef5e0; color: #a60; padding: 2px 6px; font-weight: bold;");
+            return Object.assign(Object.assign({}, state), { buffer: "", lastCorrectToken: null, anchorPending: true, anchorTokens: [] });
+        case "COMMIT_FINAL":
+            return replay(state, action.transcript, action.expected, action.alternatives);
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Hook                                                              */
+/* ------------------------------------------------------------------ */
+export function useRecitationValidator(expectedWords, alternatives = wordAlternatives) {
+    const [committed, dispatch] = useReducer(reducer, initial);
+    const [interimTranscript, setInterimTranscript] = useState("");
+    const ingestFinal = useCallback((transcript) => {
+        setInterimTranscript("");
+        dispatch({
+            type: "COMMIT_FINAL",
+            transcript,
+            expected: expectedWords,
+            alternatives,
+        });
+    }, [expectedWords, alternatives]);
+    const ingestInterim = useCallback((transcript) => {
+        setInterimTranscript(transcript);
+    }, []);
+    const reset = useCallback(() => {
+        setInterimTranscript("");
+        dispatch({ type: "RESET" });
+    }, []);
+    const jumpTo = useCallback((i) => dispatch({ type: "JUMP_TO", index: i }), []);
+    /**
+     * Re-enter anchor mode. Call after a detected silence / pause from STT,
+     * or after any external signal that the user may have shifted position.
+     * Wrong validations already trigger this automatically; this is the
+     * caller-driven path.
+     */
+    const reAnchor = useCallback(() => dispatch({ type: "RE_ANCHOR" }), []);
+    const wordHighlights = useMemo(() => {
+        const m = new Map(committed.statuses);
+        // Don't show a "current" indicator while we're still anchoring —
+        // the cursor isn't authoritative until anchor completes.
+        if (!committed.anchorPending) {
+            const cur = expectedWords[committed.currentIndex];
+            if (cur)
+                m.set(cur.key, "current");
+        }
+        return m;
+    }, [
+        committed.statuses,
+        committed.currentIndex,
+        committed.anchorPending,
+        expectedWords,
+    ]);
+    return {
+        currentIndex: committed.currentIndex,
+        buffer: committed.buffer,
+        interim: interimTranscript,
+        wordHighlights,
+        ingestFinal,
+        ingestInterim,
+        reset,
+        jumpTo,
+        reAnchor,
+        isComplete: !committed.anchorPending &&
+            committed.currentIndex >= expectedWords.length,
+        /** 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: committed.anchorPending,
+    };
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './utils';
+export * from './hooks';

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export * from './utils';
+export * from './hooks';

package/dist/esm/utils/arabic.d.ts

@@ -0,0 +1,2 @@
+export declare function removeTashkeel(text: string): string;
+export declare function normalizeArabic(input: string): string;

package/dist/esm/utils/arabic.js

@@ -0,0 +1,28 @@
+const TASHKEEL = /[\u064B-\u065F\u0670\u06D6-\u06ED]/g;
+const TATWEEL = /\u0640/g;
+export function removeTashkeel(text) {
+    return text.replace(TASHKEEL, "").replace(TATWEEL, "");
+}
+export function normalizeArabic(input) {
+    if (!input)
+        return "";
+    return (input
+        // 1. Dagger alef → regular alef.
+        .replace(/\u0670/g, "\u0627")
+        // 2. Alef variants → bare alef.
+        .replace(/[\u0622\u0623\u0625\u0671]/g, "\u0627")
+        // 3a. Yaa maksura → yaa.
+        .replace(/\u0649/g, "\u064A")
+        // 3b. Taa marbuta → haa.
+        .replace(/\u0629/g, "\u0647")
+        // 4. Strip three diacritic / annotation ranges. The U+06D6..U+06ED
+        //    range is the critical addition vs the previous version —
+        //    without it, mushaf-style text retains marks like ۡ ۦ ۖ that
+        //    inflate the expected-word length and prevent the
+        //    prefix/contained matching from firing correctly.
+        .replace(/[\u0610-\u061A\u064B-\u065F\u06D6-\u06ED]/g, "")
+        // 5. Strip tatweel + zero-width + BIDI marks + NBSP + BOM.
+        .replace(/[\u0640\u00A0\u200B-\u200F\u202A-\u202E\uFEFF]/g, "")
+        // 6. Strip all whitespace runs.
+        .replace(/\s+/g, ""));
+}

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

@@ -0,0 +1,4 @@
+export * from './arabic';
+export * from './levenshtein';
+export * from './validation';
+export * from './wordAlternatives';

package/dist/esm/utils/index.js

@@ -0,0 +1,4 @@
+export * from './arabic';
+export * from './levenshtein';
+export * from './validation';
+export * from './wordAlternatives';

package/dist/esm/utils/levenshtein.d.ts

@@ -0,0 +1,2 @@
+export declare function levenshteinDistance(a: string, b: string): number;
+export declare function similarity(a: string, b: string): number;

package/dist/esm/utils/levenshtein.js

@@ -0,0 +1,27 @@
+export function levenshteinDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1).fill(0);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+export function similarity(a, b) {
+    const maxLen = Math.max(a.length, b.length);
+    return maxLen === 0 ? 1 : 1 - levenshteinDistance(a, b) / maxLen;
+}

package/dist/esm/utils/validation.d.ts

@@ -0,0 +1,28 @@
+import { WordAlternative } from "./wordAlternatives";
+/**
+ * Standard threshold: 30% of the word's length, rounded up.
+ */
+export declare function defaultThreshold(word: string): number;
+interface ExpectedWordRef {
+    text: string;
+    surah: number;
+    verse: number;
+}
+export type ValidationStatus = "correct" | "wrong" | "pending" | "split" | "merge";
+export interface ValidationResult {
+    status: ValidationStatus;
+    advance: boolean;
+    newBuffer: string;
+    /** Present when status is "split" — the leftover portion of spoken to re-feed. */
+    remainder?: string;
+}
+/**
+ * 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".
+ */
+export declare function validateRecitation(buffer: string, expected: ExpectedWordRef[], currentIndex: number, alternatives?: WordAlternative[], lastCorrectToken?: string | null): ValidationResult;
+export {};