@quranlingoapp/recitation 0.1.0-beta.0 → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0-beta.1 (unpublished)
4
+
5
+ - Add app-bundled Hafs reference providers, with complete runtime tj3 vocabulary
6
+ checks and ayah-end reading context validation.
7
+ - Add explicit educator exercises with optional text/focus metadata and caller
8
+ phonemes. Existing ExpectedWord[] remains supported; no automatic rule scorer.
9
+ - Generate all 6,236 ayat from pinned Quran Lab quran-g2p source. Standalone
10
+ mobile-reference data is separate from the lightweight npm tarball.
11
+ - Include source/manifest hashes, word-span reconciliation data, optional symbolic
12
+ Tajweed attributes and reproducible export tooling. See docs/reference-data.md.
13
+ - Add reference/export coverage tests. Native build/device verification remains
14
+ outstanding from beta.0; no native bridge behavior changed in this release.
15
+
16
+ ## 0.1.0-beta.0
17
+
18
+ - Initial React Native Android/Apple SDK bridge, streaming results, external audio
19
+ support, conservative expected-word comparison and lifecycle handling.
package/README.md CHANGED
@@ -92,11 +92,66 @@ await engine.start({ expected: { surah: 1, ayah: 1, words: displayLabels } });
92
92
 
93
93
  This downloads/verifies the SDK reference on demand **if available**, and maps its
94
94
  units to words (Android word bars; Apple explicit word starts). Current upstream
95
- 3.1.5/3.1.4 model builds expose no reference: an ayah-only request fails explicitly
96
- with `reference_missing`; supply reviewed word phonemes instead. We do not bundle
97
- a substitute Quran text/phonetics dataset or invent one. `loadModel()` exposes the
95
+ 3.1.5/3.1.4 model builds expose no reference. Register an app-bundled Hafs reference
96
+ provider as shown below, or supply reviewed word phonemes. Without either, the
97
+ request fails explicitly with `reference_missing`. `loadModel()` exposes the
98
98
  vocabulary, blank/bar IDs, calibration JSON/hash and reference availability.
99
99
 
100
+ ## Offline Hafs reference and educator exercises (beta.1)
101
+
102
+ The source repository now includes `mobile-reference/`: deterministic precomputed
103
+ data for all 114 surahs / 6,236 ayat, generated from Quran Lab's pinned `quran-g2p`
104
+ revision and its official **tj3** renderer. There is no handwritten letter mapping.
105
+ The 114 phoneme JSON files total about 1.6 MB and are intentionally distributed
106
+ separately from npm so apps can bundle only what they need.
107
+
108
+ Copy `mobile-reference/surahs/` into the app's assets. For example:
109
+
110
+ ```ts
111
+ import { getRecitation, createHafsReferenceProvider } from '@quranlingoapp/recitation';
112
+ import type { HafsReferenceBundle } from '@quranlingoapp/recitation';
113
+
114
+ const fatiha = require('./assets/recitation/surahs/001.json') as HafsReferenceBundle;
115
+ const engine = getRecitation();
116
+ engine.setReferenceProvider(createHafsReferenceProvider(fatiha));
117
+ // Configure and load the native model as usual, then:
118
+ await engine.start({ expected: { surah: 1, ayah: 1 } });
119
+ ```
120
+
121
+ Pass an array of bundles to support several surahs. The provider checks the entire
122
+ runtime model vocabulary, blank/bar IDs and V4 generation before returning phones;
123
+ it rejects incompatibility instead of silently remapping sounds. It checks schema,
124
+ provenance fields and token IDs, but does not cryptographically authenticate imported
125
+ JSON at runtime. Verify manifest hashes during asset preparation. Register/swap
126
+ providers between sessions; native SDK reference takes precedence when available.
127
+
128
+ These files describe **full-ayah ibtida to ayah-end waqf**, with connected words
129
+ inside each ayah, Hafs/Shatibiyyah and upstream default choices. They cannot be
130
+ cropped to invent isolated-word pronunciation, arbitrary mid-ayah starts/stops or
131
+ cross-ayah wasl. Word positions are the source engine's indices; reconcile them
132
+ with your app's display edition before highlighting. See `docs/reference-data.md`.
133
+
134
+ Educators can also provide free text as a display label with explicit expected
135
+ word phonemes, without any Quran reference lookup:
136
+
137
+ ```ts
138
+ await engine.start({
139
+ expected: {
140
+ kind: 'exercise',
141
+ id: 'teacher-exercise-42',
142
+ text: teacherText,
143
+ focus: ['ghunna'],
144
+ words: teacherWords, // [{ id, text?, phonemes: exactModelTokenNames }]
145
+ },
146
+ });
147
+ ```
148
+
149
+ The result includes `exercise` metadata. `focus` records instructional intent only;
150
+ it does not enable a calibrated ghunna/gemination/qalqalah/madd scorer. Those raw
151
+ heads are already available separately. No automatic free-text phonemizer is added
152
+ to the phone runtime, and the acoustic model remains trained for Quranic recitation;
153
+ accepting custom references does not make it a universal language recognizer.
154
+
100
155
  `decoded.text` is what the SDK heard **as phoneme names**, not an unconstrained
101
156
  Arabic transcript. `matchedText` concatenates caller labels for confidently matching
102
157
  words only; it must not be described as an independent Arabic ASR transcript.
@@ -0,0 +1,100 @@
1
+ # Hafs reference data and custom exercises
2
+
3
+ ## Provenance and generation
4
+
5
+ The primary reference comes from Quran Lab's official `quran-g2p` source, pinned to
6
+ `7eeba1206146e0b4a81bbd12b59671042b1ba3f0`. The generator verifies the Git blob
7
+ hash of each pinned file, including all imported source, the original Tanzil text,
8
+ the official tj3 vocabulary and source notices. `TextBank.load('tanzil')` additionally
9
+ verifies the text's SHA-256 and handles basmala/ayah numbering. Export uses
10
+ `phonemize(..., ref=AyahRef(...))` and `phones_to_tj3`; it does not reproduce their
11
+ religious rules or invent Quran phones. Each ayah is phonemized in full context,
12
+ then split by source word index; the export asserts that rejoining the words gives
13
+ exactly the official full-ayah tj3 sequence.
14
+
15
+ Regenerate in a network-connected environment:
16
+
17
+ ```sh
18
+ git clone https://github.com/Quran-Lab/quran-g2p /tmp/quran-g2p
19
+ git -C /tmp/quran-g2p checkout 7eeba1206146e0b4a81bbd12b59671042b1ba3f0
20
+ python3 tools/export_hafs_reference.py --g2p /tmp/quran-g2p --output mobile-reference
21
+ npm test
22
+ ```
23
+
24
+ Python >=3.10; upstream runtime requires no external pip packages. Preserve the
25
+ upstream LICENSE/SOURCE-NOTICE files and original text notice in redistributed data.
26
+ Generated phonemes and attributes remain under NPL-1.2. The original text retains
27
+ Tanzil's own terms. No SDK model or credentials are included.
28
+
29
+ ## Files to use in the app
30
+
31
+ | File | Use |
32
+ | --- | --- |
33
+ | `surahs/001.json` … `114.json` | Required phoneme bundles, ~1.6 MB total; can load selected surahs |
34
+ | `manifest.json` | Pinned provenance, upstream configuration, counts, file sizes and SHA-256 |
35
+ | `attributes/*.json` | Optional symbolic ghunna, gemination, qalqalah and length prescriptions; ~12.5 MB |
36
+ | `rulings.json` | Source rule names and classical citations for the attribute sidecar |
37
+ | `word-spans.jsonl` | Source character spans for reconciling source word positions with an app's edition |
38
+ | `tanzil-uthmani-source.txt` | Original source text, verbatim, including its notice; for audit/reproduction |
39
+ | `LICENSE`, `SOURCE-NOTICE.md` | Redistribution terms/attribution |
40
+
41
+ Keep provenance/license information with the app's bundled data. Runtime matching
42
+ needs only the relevant surah JSON; Python and the source text need not run on the
43
+ device. Static Metro require() paths are simplest; a host may implement its own
44
+ asset-loading provider through `AyahReferenceProvider`. No app networking is added.
45
+
46
+ ## Word indices and reading context
47
+
48
+ Generated coverage: 6,236 ayat, **77,481 source-word positions**, 471,080 tj3 tokens
49
+ excluding word bars, from 522,475 attributed source phones. Do not assume this word
50
+ segmentation equals a Quran Foundation/Mushaf SVG dataset's numbering. In particular,
51
+ the published KFGQPC audit count is 77,429, so a cross-edition ID mapping needs explicit
52
+ validation. Optional `ExpectedAyah.words` lets the app supply its IDs only after
53
+ reconciling the order/count. The provider rejects count mismatches; equal counts
54
+ alone do not establish identical segmentation. No app repository was changed here.
55
+
56
+ `word-spans.jsonl` spans are Python Unicode code-point offsets into the source ayah
57
+ after the official TextBank basmala handling, not JavaScript UTF-16 indexes or SVG
58
+ coordinates. `textSha256` identifies that ayah string. Synthetic/merged phones can
59
+ share source spans. This sidecar helps inspect/match positions, not certify a
60
+ one-letter/one-sound relationship. Preserve host display words independently.
61
+
62
+ The first dataset supports one reading policy: start at the ayah's beginning,
63
+ connect its interior words, stop at its end. It uses the default upstream Hafs
64
+ configuration recorded in the manifest. Alternate transmitted choices, arbitrary
65
+ stops, rawm/ishmam forms, isolated-word prompts and cross-ayah joins need separately
66
+ generated references. In particular, slicing these word arrays does not regenerate
67
+ ibtida/waqf effects at the new boundaries. The provider deliberately has no range
68
+ or crop option. Longer ayat may exceed the engine's existing 256-word / 2048-phone
69
+ session bounds; raise limits only after profiling or use properly generated segments.
70
+
71
+ ## Educator-authored material
72
+
73
+ The generic `ExpectedWord[]` API is preserved. `ExpectedExercise` adds an optional
74
+ phrase label, exercise ID and instructional focus around those explicit phonemes.
75
+ No surah/ayah lookup runs for this mode. Every expected token still must exist in
76
+ the loaded acoustic model's vocabulary, and word IDs must be unique.
77
+
78
+ An educator can type a phrase and supply/review its expected phonemes, which the
79
+ app stores as exercise content. A future authoring-side text-to-phoneme service can
80
+ produce the same contract without changing audio inference. Text is a label,
81
+ not an inference prompt and not a substitute for phonemes. Non-Quran/custom Arabic
82
+ is experimental for this Quran-trained model; general multilingual recognition is
83
+ outside its supported claims. Do not use another recognizer's output as unquestioned
84
+ ground-truth pronunciation.
85
+
86
+ ## Ghunnah and other Tajweed attributes
87
+
88
+ tj3 intentionally keeps many qualities outside the token axis. A matching phoneme
89
+ sequence cannot prove a learner sustained ghunna, shadda or a madd correctly. The
90
+ optional sidecars preserve the upstream symbolic expectations with rule citations;
91
+ these are not observations or measurements. Each site carries `wordIndex` (0-based)
92
+ and `tokenIndex` into the full ayah tj3 stream including word bars. Several source
93
+ phones may map to the same long-vowel token. Length `allowed`, `scoring`, `canonical`
94
+ are prescriptions/choices, not recorded timing ground truth. Do not turn a canonical
95
+ choice into the only correct performance.
96
+
97
+ The wrapper continues returning raw heads. Rule-specific judgments require a future
98
+ scorer validated for the exact model/calibration, rule class, alignment and legal
99
+ variants. `focus: ['ghunna']` records the lesson's aim; it never fabricates a score.
100
+ Automatic feedback remains fallible and does not replace a qualified teacher.
@@ -7,10 +7,16 @@ release. No QuranLingo app repository was modified.
7
7
 
8
8
  - TypeScript 5.9.2 strict typecheck against real React Native 0.84.1 declarations.
9
9
  - TypeScript declaration/JavaScript build.
10
- - 22 Node tests: provisional/settled boundaries, confidence abstention, substitutions,
10
+ - 28 Node tests: provisional/settled boundaries, confidence abstention, substitutions,
11
11
  unrelated audio, omissions, repeated-sequence ambiguity, late provisional evidence,
12
12
  PCM16 conversion, lifecycle failures, reference fallback, replay, stale/final events,
13
- external input validation/order/backpressure and SDK rate validation.
13
+ external input validation/order/backpressure and SDK rate validation. New checks
14
+ validate every generated artifact hash, all 6,236 ayah lookups, vocabulary/context
15
+ rejection, reference provenance, offline fallback and educator-exercise behavior.
16
+ - 10 official Quran Lab tj3 renderer tests passed against the pinned source and
17
+ its original text. The generator verifies all pinned input Git blob hashes,
18
+ validates the text/vocabulary SHA-256, and checks full-ayah vs per-word rendered
19
+ sequence equality for every ayah. These are data/export checks, not device tests.
14
20
  - Ruby syntax of podspec and SPM helper; Xcodeproj test constructs, saves/reopens
15
21
  project, verifies exact SDK pin/link product, recovery from RN package-reference
16
22
  cleanup, module include paths and idempotence. The iOS helper requires dynamic
@@ -23,8 +29,9 @@ The shell has no network DNS access and no Android SDK/Gradle installation was
23
29
  available. Full npm dependency installation stopped on an uncached React Native
24
30
  transitive dependency. The actual TypeScript, React Native and React declaration
25
31
  tarballs were available in the local npm cache and used for the checks above;
26
- no synthetic React Native types were used. There is no generated lockfile from a
27
- successful complete install. Re-run normal npm install in a connected environment.
32
+ no synthetic React Native types were used. A package-lock.json was subsequently
33
+ created in the user's local publication workflow. This update uses the installed
34
+ TypeScript/RN dependencies and preserves that lockfile while bumping to beta.1.
28
35
 
29
36
  Native SDK artifacts could not be resolved, and no app-specific approved SDK keys
30
37
  were supplied. Therefore Android/iOS compilation, native linkage, runtime microphone
package/lib/engine.d.ts CHANGED
@@ -1,7 +1,8 @@
1
- import type { Configuration, ModelInfo, NativeBridge, NativeChunk, RecitationResult, SessionEvent, SessionOptions, Subscription } from './types';
1
+ import type { AyahReferenceProvider, Configuration, ModelInfo, NativeBridge, NativeChunk, RecitationResult, SessionEvent, SessionOptions, Subscription } from './types';
2
2
  export declare class RecitationEngine {
3
3
  private readonly bridge;
4
4
  private model?;
5
+ private referenceProvider?;
5
6
  private session?;
6
7
  private sequence;
7
8
  private busy;
@@ -10,6 +11,8 @@ export declare class RecitationEngine {
10
11
  private pendingAudio;
11
12
  private audioTail;
12
13
  constructor(bridge: NativeBridge);
14
+ /** Register app-bundled reference data without adding runtime networking to this package. */
15
+ setReferenceProvider(provider?: AyahReferenceProvider): void;
13
16
  private exclusive;
14
17
  configure(config: Configuration): Promise<void>;
15
18
  loadModel(): Promise<ModelInfo>;
package/lib/engine.js CHANGED
@@ -6,6 +6,7 @@ const alignment_1 = require("./alignment");
6
6
  class RecitationEngine {
7
7
  bridge;
8
8
  model;
9
+ referenceProvider;
9
10
  session;
10
11
  sequence = 0;
11
12
  busy = false;
@@ -16,6 +17,12 @@ class RecitationEngine {
16
17
  constructor(bridge) {
17
18
  this.bridge = bridge;
18
19
  }
20
+ /** Register app-bundled reference data without adding runtime networking to this package. */
21
+ setReferenceProvider(provider) {
22
+ if (this.busy || this.session?.active)
23
+ throw new Error('Set reference provider between sessions');
24
+ this.referenceProvider = provider;
25
+ }
19
26
  async exclusive(action) {
20
27
  if (this.busy)
21
28
  throw new Error('A lifecycle operation is already in progress');
@@ -63,17 +70,33 @@ class RecitationEngine {
63
70
  if (Array.isArray(options.expected)) {
64
71
  words = options.expected.map(w => ({ ...w, phonemes: [...w.phonemes] }));
65
72
  }
73
+ else if ('kind' in options.expected && options.expected.kind === 'exercise') {
74
+ if (!options.expected.id?.trim())
75
+ throw new Error('Exercise id is required');
76
+ const exercise = options.expected;
77
+ if (exercise.focus?.some(f => !['ghunna', 'gemination', 'qalqalah', 'madd', 'phonemes'].includes(f)))
78
+ throw new Error('Unknown exercise focus');
79
+ words = exercise.words.map(w => ({ ...w, phonemes: [...w.phonemes] }));
80
+ }
66
81
  else {
67
82
  const ayah = options.expected;
68
83
  if (!Number.isInteger(ayah.surah) || !Number.isInteger(ayah.ayah) || ayah.surah < 1 || ayah.surah > 114 || ayah.ayah < 1)
69
84
  throw new Error('Invalid ayah');
70
- if (!model.referenceAvailable)
71
- throw new Error('reference_missing: supply expected words with verified phonemes for this model');
72
- const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
73
- if (ayah.words && ayah.words.length !== phones.length)
74
- throw new Error('Display word count differs from SDK reference');
75
- words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
76
- text: ayah.words?.[i]?.text, phonemes }));
85
+ if (ayah.reading && ayah.reading !== 'ayah-end')
86
+ throw new Error('Unsupported reading context');
87
+ if (!model.referenceAvailable && this.referenceProvider) {
88
+ const resolved = await this.referenceProvider.resolveAyah(ayah, model);
89
+ words = resolved.map(w => ({ ...w, phonemes: [...w.phonemes] }));
90
+ }
91
+ else {
92
+ if (!model.referenceAvailable)
93
+ throw new Error('reference_missing: register bundled Hafs data or supply verified phonemes');
94
+ const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
95
+ if (ayah.words && ayah.words.length !== phones.length)
96
+ throw new Error('Display word count differs from SDK reference');
97
+ words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
98
+ text: ayah.words?.[i]?.text, phonemes }));
99
+ }
77
100
  }
78
101
  if (!words.length || words.length > 256 || words.reduce((n, w) => n + w.phonemes.length, 0) > 2048)
79
102
  throw new Error('Expected sequence must have 1..256 words and at most 2048 phonemes');
@@ -85,7 +108,10 @@ class RecitationEngine {
85
108
  ids.add(w.id);
86
109
  }
87
110
  const id = `recitation-${++this.sequence}`;
88
- this.session = { id, words, options: { ...options, thresholds: (0, alignment_1.thresholds)(options.thresholds) }, active: true };
111
+ const expected = options.expected;
112
+ const exercise = !Array.isArray(expected) && 'kind' in expected && expected.kind === 'exercise'
113
+ ? { id: expected.id, text: expected.text, focus: expected.focus ? [...expected.focus] : undefined } : undefined;
114
+ this.session = { id, words, options: { ...options, thresholds: (0, alignment_1.thresholds)(options.thresholds) }, exercise, active: true };
89
115
  try {
90
116
  await this.bridge.start(id, { source: options.source ?? 'microphone', sampleRate,
91
117
  context: options.context ?? 'c16_l64', backend: options.backend ?? 'auto', endOnSilenceMs,
@@ -160,7 +186,8 @@ class RecitationEngine {
160
186
  : s.words.map(w => ({ id: w.id, text: w.text, state: 'uncertain', committed: false,
161
187
  confidence: null, startMs: null, endMs: null, expectedPhonemes: w.phonemes,
162
188
  recognizedPhonemes: [], reason: 'alignment_ambiguous' }));
163
- const result = { ...chunk, words, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
189
+ const exercise = s.exercise ? { ...s.exercise, focus: s.exercise.focus ? [...s.exercise.focus] : undefined } : undefined;
190
+ const result = { ...chunk, words, exercise, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
164
191
  if (chunk.decoded.isFinal) {
165
192
  s.final = result;
166
193
  s.active = false;
package/lib/index.d.ts CHANGED
@@ -2,5 +2,7 @@ import { RecitationEngine } from './engine';
2
2
  export * from './types';
3
3
  export { pcm16leToFloat32 } from './engine';
4
4
  export { DEFAULT_THRESHOLDS } from './alignment';
5
+ export { createHafsReferenceProvider } from './reference';
6
+ export type { HafsReferenceBundle } from './reference';
5
7
  /** One SDK client per process. Call once and keep it for the app's lifetime. */
6
8
  export declare function getRecitation(): RecitationEngine;
package/lib/index.js CHANGED
@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.DEFAULT_THRESHOLDS = exports.pcm16leToFloat32 = void 0;
17
+ exports.createHafsReferenceProvider = exports.DEFAULT_THRESHOLDS = exports.pcm16leToFloat32 = void 0;
18
18
  exports.getRecitation = getRecitation;
19
19
  const react_native_1 = require("react-native");
20
20
  const engine_1 = require("./engine");
@@ -23,6 +23,8 @@ var engine_2 = require("./engine");
23
23
  Object.defineProperty(exports, "pcm16leToFloat32", { enumerable: true, get: function () { return engine_2.pcm16leToFloat32; } });
24
24
  var alignment_1 = require("./alignment");
25
25
  Object.defineProperty(exports, "DEFAULT_THRESHOLDS", { enumerable: true, get: function () { return alignment_1.DEFAULT_THRESHOLDS; } });
26
+ var reference_1 = require("./reference");
27
+ Object.defineProperty(exports, "createHafsReferenceProvider", { enumerable: true, get: function () { return reference_1.createHafsReferenceProvider; } });
26
28
  let instance;
27
29
  /** One SDK client per process. Call once and keep it for the app's lifetime. */
28
30
  function getRecitation() {
@@ -0,0 +1,18 @@
1
+ import type { AyahReferenceProvider } from './types';
2
+ /** One surah, generated with the pinned official Quran Lab quran-g2p tj3 renderer. */
3
+ export interface HafsReferenceBundle {
4
+ format: 'quralingo.hafs-tj3/1';
5
+ reading: 'ayah-end';
6
+ surah: number;
7
+ vocabulary: readonly string[];
8
+ source: {
9
+ repository: string;
10
+ revision: string;
11
+ textSha256: string;
12
+ vocabularySha256: string;
13
+ };
14
+ /** Ayah number -> source word order -> tj3 token IDs. */
15
+ ayahs: Readonly<Record<string, readonly (readonly number[])[]>>;
16
+ }
17
+ /** No files or network requests: the host loads/bundles the surahs it needs. */
18
+ export declare function createHafsReferenceProvider(input: HafsReferenceBundle | readonly HafsReferenceBundle[]): AyahReferenceProvider;
@@ -0,0 +1,61 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createHafsReferenceProvider = createHafsReferenceProvider;
4
+ /** No files or network requests: the host loads/bundles the surahs it needs. */
5
+ function createHafsReferenceProvider(input) {
6
+ const bundles = new Map();
7
+ const inputs = Array.isArray(input) ? input : [input];
8
+ let vocabulary;
9
+ let revision;
10
+ let textHash;
11
+ let vocabularyHash;
12
+ for (const bundle of inputs) {
13
+ if (bundle.format !== 'quralingo.hafs-tj3/1' || bundle.reading !== 'ayah-end' ||
14
+ !Number.isInteger(bundle.surah) || bundle.surah < 1 || bundle.surah > 114 || bundles.has(bundle.surah))
15
+ throw new Error('Invalid or duplicate Hafs reference bundle');
16
+ if (!/^[0-9a-f]{40}$/.test(bundle.source.revision) || !/^[0-9a-f]{64}$/.test(bundle.source.textSha256) ||
17
+ !/^[0-9a-f]{64}$/.test(bundle.source.vocabularySha256))
18
+ throw new Error('Missing reference provenance');
19
+ if (bundle.vocabulary.length !== 38 || bundle.vocabulary[0] !== '<blk>' || bundle.vocabulary[1] !== '|' ||
20
+ new Set(bundle.vocabulary).size !== 38)
21
+ throw new Error('Invalid tj3 vocabulary');
22
+ if (vocabulary && (JSON.stringify(vocabulary) !== JSON.stringify(bundle.vocabulary) || revision !== bundle.source.revision ||
23
+ textHash !== bundle.source.textSha256 || vocabularyHash !== bundle.source.vocabularySha256))
24
+ throw new Error('Mixed reference revisions/vocabularies');
25
+ vocabulary = [...bundle.vocabulary];
26
+ revision = bundle.source.revision;
27
+ textHash = bundle.source.textSha256;
28
+ vocabularyHash = bundle.source.vocabularySha256;
29
+ const copy = {};
30
+ for (const [ayah, words] of Object.entries(bundle.ayahs)) {
31
+ if (!/^[1-9][0-9]*$/.test(ayah) || !Array.isArray(words) || !words.length)
32
+ throw new Error('Invalid reference ayah');
33
+ copy[ayah] = words.map(word => {
34
+ if (!Array.isArray(word) || !word.length || word.some(id => !Number.isInteger(id) || id < 2 || id >= 37))
35
+ throw new Error('Invalid reference phoneme ID');
36
+ return [...word];
37
+ });
38
+ }
39
+ bundles.set(bundle.surah, { ...bundle, vocabulary: [...bundle.vocabulary], source: { ...bundle.source }, ayahs: copy });
40
+ }
41
+ return {
42
+ resolveAyah(request, model) {
43
+ const bundle = bundles.get(request.surah);
44
+ if (!bundle)
45
+ throw new Error(`reference_missing: surah ${request.surah} is not loaded`);
46
+ if (request.reading && request.reading !== bundle.reading)
47
+ throw new Error('Reference reading context mismatch');
48
+ // Match the complete runtime vocabulary, not merely an inferred model-generation label.
49
+ if (!model.version.startsWith('4.') || model.blank !== 0 || model.wordBar !== 1 ||
50
+ JSON.stringify(model.tokens) !== JSON.stringify(bundle.vocabulary))
51
+ throw new Error('reference_incompatible: runtime model does not match this tj3 vocabulary');
52
+ const words = bundle.ayahs[String(request.ayah)];
53
+ if (!words)
54
+ throw new Error(`reference_missing: ayah ${request.surah}:${request.ayah}`);
55
+ if (request.words && request.words.length !== words.length)
56
+ throw new Error('Display word count differs from source reference; reconcile word IDs before using feedback');
57
+ return words.map((ids, index) => ({ id: request.words?.[index]?.id ?? `${request.surah}:${request.ayah}:${index + 1}`,
58
+ text: request.words?.[index]?.text, phonemes: ids.map(id => bundle.vocabulary[id]) }));
59
+ },
60
+ };
61
+ }
package/lib/types.d.ts CHANGED
@@ -14,6 +14,20 @@ export interface ExpectedAyah {
14
14
  id: string;
15
15
  text?: string;
16
16
  }[];
17
+ /** Precomputed data currently supports a fresh start and stop at the ayah end. */
18
+ reading?: 'ayah-end';
19
+ }
20
+ /** Educators author the expected pronunciation; display text never drives recognition. */
21
+ export interface ExpectedExercise {
22
+ kind: 'exercise';
23
+ id: string;
24
+ text?: string;
25
+ words: readonly ExpectedWord[];
26
+ /** Instructional intent only. Raw heads are returned; no rule scorer is implied. */
27
+ focus?: readonly ('ghunna' | 'gemination' | 'qalqalah' | 'madd' | 'phonemes')[];
28
+ }
29
+ export interface AyahReferenceProvider {
30
+ resolveAyah(request: ExpectedAyah, model: ModelInfo): Promise<readonly ExpectedWord[]> | readonly ExpectedWord[];
17
31
  }
18
32
  export interface Token {
19
33
  id: number;
@@ -64,6 +78,12 @@ export interface WordFeedback {
64
78
  }
65
79
  export interface RecitationResult extends NativeChunk {
66
80
  words: WordFeedback[];
81
+ /** Exercise metadata, not a measured Tajweed rule score. */
82
+ exercise?: {
83
+ id: string;
84
+ text?: string;
85
+ focus?: ExpectedExercise['focus'];
86
+ };
67
87
  /** Expected labels for matching words only; not an unconstrained Arabic transcript. */
68
88
  matchedText: string;
69
89
  }
@@ -80,7 +100,7 @@ export interface Configuration {
80
100
  audience?: 'children' | 'general';
81
101
  }
82
102
  export interface SessionOptions {
83
- expected: readonly ExpectedWord[] | ExpectedAyah;
103
+ expected: readonly ExpectedWord[] | ExpectedAyah | ExpectedExercise;
84
104
  source?: 'microphone' | 'external';
85
105
  /** External float samples only: supported SDK rate; default 16000. */
86
106
  sampleRate?: number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quranlingoapp/recitation",
3
- "version": "0.1.0-beta.0",
3
+ "version": "0.1.0-beta.1",
4
4
  "description": "React Native streaming bridge for Quran Lab TajweedFormer V4",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -20,6 +20,7 @@
20
20
  "docs",
21
21
  "LICENSE",
22
22
  "NOTICE",
23
+ "CHANGELOG.md",
23
24
  "README.md"
24
25
  ],
25
26
  "scripts": {
package/src/engine.ts CHANGED
@@ -1,10 +1,12 @@
1
1
  import { alignWords, thresholds } from './alignment';
2
- import type { Configuration, ExpectedWord, ModelInfo, NativeBridge, NativeChunk, RecitationResult,
2
+ import type { AyahReferenceProvider, Configuration, ExpectedExercise, ExpectedWord, ModelInfo, NativeBridge, NativeChunk, RecitationResult,
3
3
  SessionEvent, SessionOptions, Subscription } from './types';
4
4
 
5
5
  export class RecitationEngine {
6
6
  private model?: ModelInfo;
7
- private session?: { id: string; words: ExpectedWord[]; options: SessionOptions; active: boolean; final?: RecitationResult };
7
+ private referenceProvider?: AyahReferenceProvider;
8
+ private session?: { id: string; words: ExpectedWord[]; options: SessionOptions; active: boolean; final?: RecitationResult;
9
+ exercise?: RecitationResult['exercise'] };
8
10
  private sequence = 0;
9
11
  private busy = false;
10
12
  private resultListeners = new Set<(r: RecitationResult) => void>();
@@ -13,6 +15,12 @@ export class RecitationEngine {
13
15
  private audioTail: Promise<void> = Promise.resolve();
14
16
  constructor(private readonly bridge: NativeBridge) {}
15
17
 
18
+ /** Register app-bundled reference data without adding runtime networking to this package. */
19
+ setReferenceProvider(provider?: AyahReferenceProvider): void {
20
+ if (this.busy || this.session?.active) throw new Error('Set reference provider between sessions');
21
+ this.referenceProvider = provider;
22
+ }
23
+
16
24
  private async exclusive<T>(action: () => Promise<T>): Promise<T> {
17
25
  if (this.busy) throw new Error('A lifecycle operation is already in progress');
18
26
  this.busy = true;
@@ -45,14 +53,25 @@ export class RecitationEngine {
45
53
  let words: ExpectedWord[];
46
54
  if (Array.isArray(options.expected)) {
47
55
  words = options.expected.map(w => ({ ...w, phonemes: [...w.phonemes] }));
56
+ } else if ('kind' in options.expected && options.expected.kind === 'exercise') {
57
+ if (!options.expected.id?.trim()) throw new Error('Exercise id is required');
58
+ const exercise = options.expected as ExpectedExercise;
59
+ if (exercise.focus?.some(f => !['ghunna', 'gemination', 'qalqalah', 'madd', 'phonemes'].includes(f))) throw new Error('Unknown exercise focus');
60
+ words = exercise.words.map(w => ({ ...w, phonemes: [...w.phonemes] }));
48
61
  } else {
49
62
  const ayah = options.expected as import('./types').ExpectedAyah;
50
63
  if (!Number.isInteger(ayah.surah) || !Number.isInteger(ayah.ayah) || ayah.surah < 1 || ayah.surah > 114 || ayah.ayah < 1) throw new Error('Invalid ayah');
51
- if (!model.referenceAvailable) throw new Error('reference_missing: supply expected words with verified phonemes for this model');
52
- const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
53
- if (ayah.words && ayah.words.length !== phones.length) throw new Error('Display word count differs from SDK reference');
54
- words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
55
- text: ayah.words?.[i]?.text, phonemes }));
64
+ if (ayah.reading && ayah.reading !== 'ayah-end') throw new Error('Unsupported reading context');
65
+ if (!model.referenceAvailable && this.referenceProvider) {
66
+ const resolved = await this.referenceProvider.resolveAyah(ayah, model);
67
+ words = resolved.map(w => ({ ...w, phonemes: [...w.phonemes] }));
68
+ } else {
69
+ if (!model.referenceAvailable) throw new Error('reference_missing: register bundled Hafs data or supply verified phonemes');
70
+ const phones = await this.bridge.reference(ayah.surah, ayah.ayah);
71
+ if (ayah.words && ayah.words.length !== phones.length) throw new Error('Display word count differs from SDK reference');
72
+ words = phones.map((phonemes, i) => ({ id: ayah.words?.[i]?.id ?? `${ayah.surah}:${ayah.ayah}:${i + 1}`,
73
+ text: ayah.words?.[i]?.text, phonemes }));
74
+ }
56
75
  }
57
76
  if (!words.length || words.length > 256 || words.reduce((n, w) => n + w.phonemes.length, 0) > 2048) throw new Error('Expected sequence must have 1..256 words and at most 2048 phonemes');
58
77
  const ids = new Set<string>();
@@ -62,7 +81,10 @@ export class RecitationEngine {
62
81
  ids.add(w.id);
63
82
  }
64
83
  const id = `recitation-${++this.sequence}`;
65
- this.session = { id, words, options: { ...options, thresholds: thresholds(options.thresholds) }, active: true };
84
+ const expected = options.expected;
85
+ const exercise = !Array.isArray(expected) && 'kind' in expected && expected.kind === 'exercise'
86
+ ? { id: expected.id, text: expected.text, focus: expected.focus ? [...expected.focus] : undefined } : undefined;
87
+ this.session = { id, words, options: { ...options, thresholds: thresholds(options.thresholds) }, exercise, active: true };
66
88
  try {
67
89
  await this.bridge.start(id, { source: options.source ?? 'microphone', sampleRate,
68
90
  context: options.context ?? 'c16_l64', backend: options.backend ?? 'auto', endOnSilenceMs,
@@ -123,7 +145,8 @@ export class RecitationEngine {
123
145
  : s.words.map(w => ({ id: w.id, text: w.text, state: 'uncertain' as const, committed: false,
124
146
  confidence: null, startMs: null, endMs: null, expectedPhonemes: w.phonemes,
125
147
  recognizedPhonemes: [], reason: 'alignment_ambiguous' as const }));
126
- const result = { ...chunk, words, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
148
+ const exercise = s.exercise ? { ...s.exercise, focus: s.exercise.focus ? [...s.exercise.focus] : undefined } : undefined;
149
+ const result = { ...chunk, words, exercise, matchedText: words.filter(w => w.state === 'correct').map(w => w.text ?? '').filter(Boolean).join(' ') };
127
150
  if (chunk.decoded.isFinal) { s.final = result; s.active = false; }
128
151
  for (const listener of this.resultListeners) listener(result);
129
152
  }
package/src/index.ts CHANGED
@@ -4,6 +4,8 @@ import type { NativeBridge, NativeChunk, SessionEvent } from './types';
4
4
  export * from './types';
5
5
  export { pcm16leToFloat32 } from './engine';
6
6
  export { DEFAULT_THRESHOLDS } from './alignment';
7
+ export { createHafsReferenceProvider } from './reference';
8
+ export type { HafsReferenceBundle } from './reference';
7
9
 
8
10
  let instance: RecitationEngine | undefined;
9
11
  /** One SDK client per process. Call once and keep it for the app's lifetime. */
@@ -0,0 +1,58 @@
1
+ import type { AyahReferenceProvider, ExpectedAyah, ExpectedWord, ModelInfo } from './types';
2
+
3
+ /** One surah, generated with the pinned official Quran Lab quran-g2p tj3 renderer. */
4
+ export interface HafsReferenceBundle {
5
+ format: 'quralingo.hafs-tj3/1';
6
+ reading: 'ayah-end';
7
+ surah: number;
8
+ vocabulary: readonly string[];
9
+ source: { repository: string; revision: string; textSha256: string; vocabularySha256: string };
10
+ /** Ayah number -> source word order -> tj3 token IDs. */
11
+ ayahs: Readonly<Record<string, readonly (readonly number[])[]>>;
12
+ }
13
+
14
+ /** No files or network requests: the host loads/bundles the surahs it needs. */
15
+ export function createHafsReferenceProvider(input: HafsReferenceBundle | readonly HafsReferenceBundle[]): AyahReferenceProvider {
16
+ const bundles = new Map<number, HafsReferenceBundle>();
17
+ const inputs: readonly HafsReferenceBundle[] = Array.isArray(input) ? input : [input as HafsReferenceBundle];
18
+ let vocabulary: readonly string[] | undefined;
19
+ let revision: string | undefined;
20
+ let textHash: string | undefined;
21
+ let vocabularyHash: string | undefined;
22
+ for (const bundle of inputs) {
23
+ if (bundle.format !== 'quralingo.hafs-tj3/1' || bundle.reading !== 'ayah-end' ||
24
+ !Number.isInteger(bundle.surah) || bundle.surah < 1 || bundle.surah > 114 || bundles.has(bundle.surah)) throw new Error('Invalid or duplicate Hafs reference bundle');
25
+ if (!/^[0-9a-f]{40}$/.test(bundle.source.revision) || !/^[0-9a-f]{64}$/.test(bundle.source.textSha256) ||
26
+ !/^[0-9a-f]{64}$/.test(bundle.source.vocabularySha256)) throw new Error('Missing reference provenance');
27
+ if (bundle.vocabulary.length !== 38 || bundle.vocabulary[0] !== '<blk>' || bundle.vocabulary[1] !== '|' ||
28
+ new Set(bundle.vocabulary).size !== 38) throw new Error('Invalid tj3 vocabulary');
29
+ if (vocabulary && (JSON.stringify(vocabulary) !== JSON.stringify(bundle.vocabulary) || revision !== bundle.source.revision ||
30
+ textHash !== bundle.source.textSha256 || vocabularyHash !== bundle.source.vocabularySha256)) throw new Error('Mixed reference revisions/vocabularies');
31
+ vocabulary = [...bundle.vocabulary]; revision = bundle.source.revision;
32
+ textHash = bundle.source.textSha256; vocabularyHash = bundle.source.vocabularySha256;
33
+ const copy: Record<string, number[][]> = {};
34
+ for (const [ayah, words] of Object.entries(bundle.ayahs)) {
35
+ if (!/^[1-9][0-9]*$/.test(ayah) || !Array.isArray(words) || !words.length) throw new Error('Invalid reference ayah');
36
+ copy[ayah] = words.map(word => {
37
+ if (!Array.isArray(word) || !word.length || word.some(id => !Number.isInteger(id) || id < 2 || id >= 37)) throw new Error('Invalid reference phoneme ID');
38
+ return [...word];
39
+ });
40
+ }
41
+ bundles.set(bundle.surah, { ...bundle, vocabulary: [...bundle.vocabulary], source: { ...bundle.source }, ayahs: copy });
42
+ }
43
+ return {
44
+ resolveAyah(request: ExpectedAyah, model: ModelInfo): ExpectedWord[] {
45
+ const bundle = bundles.get(request.surah);
46
+ if (!bundle) throw new Error(`reference_missing: surah ${request.surah} is not loaded`);
47
+ if (request.reading && request.reading !== bundle.reading) throw new Error('Reference reading context mismatch');
48
+ // Match the complete runtime vocabulary, not merely an inferred model-generation label.
49
+ if (!model.version.startsWith('4.') || model.blank !== 0 || model.wordBar !== 1 ||
50
+ JSON.stringify(model.tokens) !== JSON.stringify(bundle.vocabulary)) throw new Error('reference_incompatible: runtime model does not match this tj3 vocabulary');
51
+ const words = bundle.ayahs[String(request.ayah)];
52
+ if (!words) throw new Error(`reference_missing: ayah ${request.surah}:${request.ayah}`);
53
+ if (request.words && request.words.length !== words.length) throw new Error('Display word count differs from source reference; reconcile word IDs before using feedback');
54
+ return words.map((ids, index) => ({ id: request.words?.[index]?.id ?? `${request.surah}:${request.ayah}:${index + 1}`,
55
+ text: request.words?.[index]?.text, phonemes: ids.map(id => bundle.vocabulary[id]!) }));
56
+ },
57
+ };
58
+ }
package/src/types.ts CHANGED
@@ -11,6 +11,20 @@ export interface ExpectedAyah {
11
11
  ayah: number;
12
12
  /** Optional display labels, in reference word order. */
13
13
  words?: readonly { id: string; text?: string }[];
14
+ /** Precomputed data currently supports a fresh start and stop at the ayah end. */
15
+ reading?: 'ayah-end';
16
+ }
17
+ /** Educators author the expected pronunciation; display text never drives recognition. */
18
+ export interface ExpectedExercise {
19
+ kind: 'exercise';
20
+ id: string;
21
+ text?: string;
22
+ words: readonly ExpectedWord[];
23
+ /** Instructional intent only. Raw heads are returned; no rule scorer is implied. */
24
+ focus?: readonly ('ghunna' | 'gemination' | 'qalqalah' | 'madd' | 'phonemes')[];
25
+ }
26
+ export interface AyahReferenceProvider {
27
+ resolveAyah(request: ExpectedAyah, model: ModelInfo): Promise<readonly ExpectedWord[]> | readonly ExpectedWord[];
14
28
  }
15
29
  export interface Token {
16
30
  id: number; name: string; firstMs: number; peakMs: number; lastMs: number;
@@ -40,6 +54,8 @@ export interface WordFeedback {
40
54
  }
41
55
  export interface RecitationResult extends NativeChunk {
42
56
  words: WordFeedback[];
57
+ /** Exercise metadata, not a measured Tajweed rule score. */
58
+ exercise?: { id: string; text?: string; focus?: ExpectedExercise['focus'] };
43
59
  /** Expected labels for matching words only; not an unconstrained Arabic transcript. */
44
60
  matchedText: string;
45
61
  }
@@ -56,7 +72,7 @@ export interface Configuration {
56
72
  audience?: 'children' | 'general';
57
73
  }
58
74
  export interface SessionOptions {
59
- expected: readonly ExpectedWord[] | ExpectedAyah;
75
+ expected: readonly ExpectedWord[] | ExpectedAyah | ExpectedExercise;
60
76
  source?: 'microphone' | 'external';
61
77
  /** External float samples only: supported SDK rate; default 16000. */
62
78
  sampleRate?: number;