Grading a tree without losing the text

This lesson describes the shared-opening quiz change in Namaq PR #413 (commit 5f4475e2). The challenge is recorded in A tree answer must preserve the path.

A node is a run of words

The explorer compresses shared word sequences into nodes. A node stores its own words, the ayat that end there, and its children. Ending an ayah does not require ending a branch (src/lib/quran/branches.ts).

Take the real opening يطوف عليهم, allowing the leading و variant. Three ayat produce three nodes after the supplied opening:

The answer has three fields. Node 2 is both an answer and the end of 56:17. Showing references only at leaves would hide that ayah. The feedback renderer reads each matched node's ayat, including internal nodes (src/app/quizzes/BranchAnswers.tsx).

Match a path, then its words

The quiz uses the explorer's BranchTree with a custom renderer for each non-root node. Before checking, it shows fields and the supplied opening; answer words and reader links appear in feedback (src/app/quran/branches/BranchTree.tsx).

Grading visits nodes in depth-first order. It tries permutations of siblings, recursively rejects pairs whose child counts differ, and chooses the valid pairing with the most correct nodes. Swapping siblings therefore moves their whole subtrees. In the example, the five-word leaf cannot trade places with the node that has a child. Each field must match every word at its assigned node; answering only غلمان or leaving node 3 blank fails completion (src/lib/quiz/branchAnswers.ts).

Forgive spelling without changing the answer

The word matcher accepts ordinary keyboard spelling of the mushaf text. Spaces and vowel marks do not decide correctness. Expected hamza seats can accept the corresponding bare keyboard letter: يوميذ matches يومئذ, and شي matches شَىْءٍ. It does not use a general edit-distance threshold; حي still fails for شَىْءٍ. The accepted variants come from the expected word's pattern (src/lib/quiz/branchAnswers.ts).

Primary sources: src/app/quran/branches/ayat.json supplies the worked example; src/lib/quiz/branchQuestions.test.ts checks the real tree; src/lib/quiz/branchAnswers.test.ts checks spelling; docs/quiz-ayah-branches.md states the quiz rules.