calliope-ts 0.0.1

package/dist/phonological.js

@@ -0,0 +1,788 @@
+// phonological.ts — Constructs the prosodic hierarchy (CP, PP, IU)
+// from the parsed sentence, replicating McAleese’s method.
+import { isPunctuation } from './parser.js';
+/**
+ * Build the full phonological hierarchy for a sentence.
+ *
+ * 1. Split into Intonational Units at punctuation tokens.
+ * 2. Within each IU, build Clitic Groups by attaching function words
+ *    to their governing content word (contiguous grouping).
+ * 3. Group Clitic Groups into Phonological Phrases using the phrase
+ *    structure tree (PPs correspond to VP and PP nodes).
+ */
+export function buildPhonologicalHierarchy(sentence) {
+    const words = sentence.words;
+    if (words.length === 0)
+        return [];
+    // ---- Step 1: split into IU segments by punctuation ----
+    const iuSegments = splitByPunctuation(words);
+    const ius = [];
+    for (const seg of iuSegments) {
+        // ---- Step 2: build Clitic Groups for this segment ----
+        const cgs = buildCliticGroups(seg);
+        // ---- Step 3: group CPs into PPs using the phrase tree ----
+        const pps = groupIntoPhonologicalPhrases(cgs, seg, sentence.nodes);
+        ius.push({ phonologicalPhrases: pps });
+    }
+    return ius;
+}
+// ─── Intonational Unit splitting ───────────────────────────────
+/** Punctuation POS tags that trigger an IU boundary.  Quotation marks are
+ *  deliberately EXCLUDED: quotes are not prosodic breaks (a quoted word inside
+ *  a clause is read in one breath), and treating them as IU boundaries
+ *  fragmented the line's phonological hierarchy — flipping meters.  Parentheses
+ *  stay: a parenthetical aside IS an intonational break. */
+const PUNCT_TAGS = new Set([
+    '.', ',', ':', ';', '!', '?',
+    '-LRB-', '-RRB-', '(', ')', // parentheses (true parentheticals);
+    '[', ']', '{', '}', // FinNLP emits literal bracket tags
+]);
+function splitByPunctuation(words) {
+    const segments = [];
+    let current = [];
+    for (const w of words) {
+        if (PUNCT_TAGS.has(w.lexicalClass)) {
+            // The punctuation token itself is not part of the prosodic
+            // hierarchy; it acts as a boundary.
+            if (current.length > 0) {
+                segments.push(current);
+                current = [];
+            }
+        }
+        else {
+            current.push(w);
+        }
+    }
+    if (current.length > 0)
+        segments.push(current);
+    return segments;
+}
+// ─── Clitic Group construction ────────────────────────────────
+/**
+ * Content‑word POS tags (expand as needed).
+ * Content words serve as the head of a Clitic Group.
+ */
+const CONTENT_TAGS = new Set([
+    'NN', 'NNS', 'NNP', 'NNPS', // nouns
+    'JJ', 'JJR', 'JJS', // adjectives
+    'VB', 'VBD', 'VBG', 'VBN', 'VBP', 'VBZ', // verbs (excl. modals)
+    'RB', 'RBR', 'RBS', // adverbs
+    'CD', // cardinal numbers (content‑like)
+]);
+function isContent(w) {
+    return CONTENT_TAGS.has(w.lexicalClass);
+}
+/**
+ * Build contiguous Clitic Groups for a segment of words.
+ *
+ * A CP consists of exactly one content word plus any contiguous
+ * function words that are dependents of that content word.
+ * Function words attach to the nearest content word to their right
+ * if they depend on it, or to the left content word otherwise.
+ */
+function buildCliticGroups(words) {
+    const groups = [];
+    const assigned = new Set();
+    // First pass: create CPs for all content words and attach their dependents
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        if (assigned.has(w))
+            continue;
+        if (isContent(w)) {
+            // Start a new CP with this content word.
+            const cpWords = [];
+            // Attach preceding unassigned function words that depend on w.
+            // Skip over already-assigned content words to reach function words.
+            let j = i - 1;
+            while (j >= 0) {
+                const prev = words[j];
+                if (assigned.has(prev)) {
+                    j--;
+                    continue; // skip assigned words (content or otherwise)
+                }
+                if (isContent(prev))
+                    break; // unassigned content → stop
+                // prev is an unassigned function word
+                if (dependsOn(prev, w)) {
+                    cpWords.unshift(prev);
+                    assigned.add(prev);
+                }
+                else {
+                    break;
+                }
+                j--;
+            }
+            // Add the content word itself.
+            cpWords.push(w);
+            assigned.add(w);
+            // Attach following unassigned function words that depend on w.
+            // Skip over already-assigned content words.
+            let k = i + 1;
+            while (k < words.length) {
+                const next = words[k];
+                if (assigned.has(next)) {
+                    k++;
+                    continue; // skip assigned words
+                }
+                if (isContent(next))
+                    break; // unassigned content → stop
+                // next is an unassigned function word
+                if (dependsOn(next, w)) {
+                    cpWords.push(next);
+                    assigned.add(next);
+                }
+                else {
+                    break;
+                }
+                k++;
+            }
+            groups.push({ tokens: cpWords });
+        }
+    }
+    // Second pass: any remaining unassigned function words become degenerate CPs
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        if (!assigned.has(w)) {
+            groups.push({ tokens: [w] });
+            assigned.add(w);
+        }
+    }
+    // Sort groups by the index of their first token to maintain sentence order
+    groups.sort((a, b) => a.tokens[0].index - b.tokens[0].index);
+    return groups;
+}
+/** True if `dependent` has `head` as its direct governor. */
+function dependsOn(dependent, head) {
+    const dep = dependent.dependency;
+    return !!(dep && dep.governor === head);
+}
+// ─── Phonological Phrase grouping via phrase tree ──────────────
+/**
+ * Assigns each CP (identified by its head word) to a Phonological
+ * Phrase.  The mapping uses the phrase‑structure tree: a PP node
+ * (or VP node) becomes a Phonological Phrase containing all CPs
+ * whose head words fall inside that node’s subtree.
+ */
+function groupIntoPhonologicalPhrases(cgs, segmentWords, rootNode) {
+    if (!rootNode) {
+        // Fallback: every CP is its own PP.
+        return cgs.map(cg => ({ cliticGroups: [cg] }));
+    }
+    // Collect all phrase nodes that are candidates for PPs:
+    // VP and PP nodes (as in Antelope’s output, VP and PP are the
+    // maximal projections that McAleese uses as PPs).
+    const phraseNodes = collectPhraseNodes(rootNode);
+    // For each CP, determine which phrase node contains its head word,
+    // preferring the smallest (most specific) node.
+    const cpToPP = new Map();
+    for (const cg of cgs) {
+        const headWord = cg.tokens.find(w => isContent(w));
+        if (!headWord) {
+            cpToPP.set(cg, null);
+            continue;
+        }
+        const containingNode = findMinimalContainingNode(headWord, phraseNodes);
+        cpToPP.set(cg, containingNode);
+    }
+    // Build PP objects: each unique phrase node becomes a PP,
+    // containing all CPs assigned to it.  CPs with no containing node
+    // are grouped into a single “orphan” PP.
+    const ppMap = new Map();
+    for (const cg of cgs) {
+        const node = cpToPP.get(cg) ?? null;
+        if (!ppMap.has(node))
+            ppMap.set(node, []);
+        ppMap.get(node).push(cg);
+    }
+    // Merge orphan CPs (node=null) into the PP of the nearest adjacent
+    // non-orphan CP within the same IU segment. This ensures function-word
+    // CPs (like determiners) that have no parse-tree node stay with the
+    // CPs they modify.
+    // Strategy: iterate CPs in order; if an orphan sits next to a non-orphan
+    // in the ordered list, merge it into that non-orphan's PP.
+    const orphanPPKey = { index: '__orphan_group__', nodeName: '__orphan_group__', parent: null, contains: [] };
+    if (ppMap.has(null)) {
+        const orphans = ppMap.get(null);
+        ppMap.delete(null);
+        // Create a synthetic key for all orphans so they merge with nearest adjacent PP.
+        // We'll merge them in the final ordering step below.
+        ppMap.set(orphanPPKey, []);
+    }
+    // Build PPs respecting order and merging adjacent orphans into
+    // the nearest non-orphan PP.
+    const cgOrder = [...cgs].sort((a, b) => a.tokens[0].index - b.tokens[0].index);
+    // Collect unique non-orphan node keys in order
+    const nodeKeysInOrder = [];
+    for (const cg of cgOrder) {
+        const node = cpToPP.get(cg) ?? null;
+        if (node === null)
+            continue; // orphans handled below
+        if (!nodeKeysInOrder.includes(node)) {
+            nodeKeysInOrder.push(node);
+        }
+    }
+    // Assign each orphan CG to the PP of the nearest adjacent non-orphan CG.
+    const orphanToNode = new Map();
+    for (const cg of cgOrder) {
+        const node = cpToPP.get(cg) ?? null;
+        if (node !== null)
+            continue; // not an orphan
+        // Look backward for nearest non-orphan CG
+        let foundNode = null;
+        for (let idx = cgOrder.indexOf(cg) - 1; idx >= 0; idx--) {
+            const n = cpToPP.get(cgOrder[idx]) ?? null;
+            if (n !== null) {
+                foundNode = n;
+                break;
+            }
+        }
+        // If none found backward, look forward
+        if (!foundNode) {
+            for (let idx = cgOrder.indexOf(cg) + 1; idx < cgOrder.length; idx++) {
+                const n = cpToPP.get(cgOrder[idx]) ?? null;
+                if (n !== null) {
+                    foundNode = n;
+                    break;
+                }
+            }
+        }
+        orphanToNode.set(cg, foundNode);
+    }
+    // Build PP objects: each unique phrase node becomes a PP,
+    // containing all CPs assigned to it (including merged orphans).
+    const finalPPMap = new Map();
+    for (const cg of cgOrder) {
+        const node = cpToPP.get(cg) ?? null;
+        const effectiveNode = node !== null ? node : (orphanToNode.get(cg) ?? orphanPPKey);
+        if (!finalPPMap.has(effectiveNode))
+            finalPPMap.set(effectiveNode, []);
+        finalPPMap.get(effectiveNode).push(cg);
+    }
+    const pps = [];
+    for (const [, cpList] of finalPPMap) {
+        cpList.sort((a, b) => a.tokens[0].index - b.tokens[0].index);
+        pps.push({ cliticGroups: cpList });
+    }
+    pps.sort((a, b) => a.cliticGroups[0].tokens[0].index - b.cliticGroups[0].tokens[0].index);
+    return pps;
+}
+/** Recursively collect all major syntactic constituent nodes (VP, PP, NP, ADJP, ADVP). */
+function collectPhraseNodes(node) {
+    const result = [];
+    const phraseTypes = new Set(['VP', 'PP', 'NP', 'ADJP', 'ADVP']);
+    if (phraseTypes.has(node.nodeName)) {
+        result.push(node);
+    }
+    for (const child of node.contains) {
+        // Skip ClsWord leaves (they have a `word` property)
+        if (child.word !== undefined)
+            continue;
+        // Now child must be a ClsNode
+        const childNode = child;
+        if (childNode.nodeName !== undefined) {
+            result.push(...collectPhraseNodes(childNode));
+        }
+    }
+    return result;
+}
+/**
+ * Find the smallest phrase node (from the candidate list) that
+ * contains the given word, or null if none does.
+ */
+function findMinimalContainingNode(word, phraseNodes) {
+    let best = null;
+    let bestSize = Infinity;
+    for (const node of phraseNodes) {
+        if (nodeContainsWord(node, word)) {
+            const size = nodeSize(node);
+            if (size < bestSize) {
+                bestSize = size;
+                best = node;
+            }
+        }
+    }
+    return best;
+}
+/** Check whether a node’s subtree includes the given word. */
+function nodeContainsWord(node, word) {
+    for (const child of node.contains) {
+        if (child.word !== undefined && child.index !== undefined) {
+            if (child.index === word.index)
+                return true;
+        }
+        else if (child.nodeName !== undefined) {
+            if (nodeContainsWord(child, word))
+                return true;
+        }
+    }
+    return false;
+}
+/** Approximate size of a node’s subtree (number of word leaves). */
+function nodeSize(node) {
+    let count = 0;
+    for (const child of node.contains) {
+        if (child.word !== undefined) {
+            // leaf word
+            count++;
+        }
+        else if (child.nodeName !== undefined) {
+            count += nodeSize(child);
+        }
+    }
+    return count;
+}
+// ─── Utility exports for scansion.ts and index.ts ─────────────
+export function collectIUTokens(iu) {
+    const tokens = [];
+    for (const pp of iu.phonologicalPhrases) {
+        tokens.push(...collectPPTokens(pp));
+    }
+    return tokens;
+}
+export function collectPPTokens(pp) {
+    const tokens = [];
+    for (const cg of pp.cliticGroups) {
+        tokens.push(...cg.tokens);
+    }
+    return tokens;
+}
+function flattenWithMeta(words) {
+    const result = [];
+    let idx = 0;
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass))
+            continue;
+        const syls = w.syllables;
+        for (let i = 0; i < syls.length; i++) {
+            result.push({
+                stress: syls[i].relativeStress ?? 'w',
+                globalIndex: idx,
+                isFinalSylOfWord: i === syls.length - 1,
+            });
+            idx++;
+        }
+    }
+    return result;
+}
+/**
+ * Core renderer that walks the hierarchy and produces the bracket string.
+ * If `keySet` is given, only positions whose global index is in the set are
+ * shown with their actual stress; all other positions become 'x'.
+ */
+function renderStressString(ius, flat, keySet) {
+    let result = '';
+    let sylIdx = 0; // pointer into flat array
+    for (const iu of ius) {
+        result += '<';
+        for (const pp of iu.phonologicalPhrases) {
+            result += '{';
+            for (const cg of pp.cliticGroups) {
+                result += '[';
+                let firstWord = true;
+                for (const word of cg.tokens) {
+                    if (!firstWord)
+                        result += '/'; // word break marker
+                    firstWord = false;
+                    const syls = word.syllables;
+                    // polysyllabic word: insert '\' before first syllable
+                    if (syls.length > 1)
+                        result += '\\';
+                    for (let s = 0; s < syls.length; s++) {
+                        const meta = flat[sylIdx];
+                        sylIdx++;
+                        const stress = meta.stress;
+                        if (keySet) {
+                            result += keySet.has(meta.globalIndex) ? stress : 'x';
+                        }
+                        else {
+                            result += stress;
+                        }
+                    }
+                }
+                result += ']';
+            }
+            result += '}';
+        }
+        result += '>';
+    }
+    return result;
+}
+/**
+ * Render the full phonological hierarchy into the bracket notation
+ * used by McAleese, e.g. "<{[nm/ws\n]}mn/sw\]m]}>".
+ */
+export function renderHierarchy(ius, words) {
+    const flat = flattenWithMeta(words);
+    return renderStressString(ius, flat);
+}
+/**
+ * Render the key‑stress string: only syllables that participate in
+ * key‑stress patterns are shown with their stress symbol; all others become 'x'.
+ */
+export function renderKeyStresses(ius, words, keyStresses) {
+    const flat = flattenWithMeta(words);
+    const keySet = new Set();
+    for (const ks of keyStresses) {
+        for (const pos of ks.positions) {
+            keySet.add(pos);
+        }
+    }
+    return renderStressString(ius, flat, keySet);
+}
+// ─── DISPLAY HELPERS ─────────────────────────────────────────────
+/**
+ * Split a word into orthographic syllable chunks using the Maximum Onset Principle.
+ * Respects English phonotactics: digraphs stay together, consonants go to
+ * the onset of the following syllable when they form a legal cluster.
+ */
+const VOWEL_CHARS = new Set('aeiouyAEIOUY');
+const CONSONANT_DIGRAPHS = new Set(['th', 'sh', 'ch', 'wh', 'ph', 'gh', 'ck', 'ng', 'nk', 'tch', 'dge', 'sc', 'sk', 'sp', 'st']);
+// ARPABET vowels, split into "free/long" (can end a syllable → favours an OPEN
+// split: e·ven, ta·ble, o·pen) and "checked/short" (needs a coda → favours a
+// CLOSED split: sev·en, prob·lem, rob·in).  This is the vowel-length cue that
+// orthography alone cannot supply; it comes from nounsing-pro's per-syllable
+// phones.  Display-only: it never affects meter scoring.
+const ARPABET_VOWELS = new Set([
+    'AA', 'AE', 'AH', 'AO', 'AW', 'AY', 'EH', 'ER', 'EY', 'IH', 'IY', 'OW', 'OY', 'UH', 'UW',
+]);
+const FREE_VOWELS = new Set(['IY', 'EY', 'AY', 'OW', 'UW', 'AW', 'OY', 'ER', 'AO']);
+/** Classify a syllable's vowel (from its ARPABET phones) as free/long vs checked/short. */
+export function vowelLengthOf(phones) {
+    if (!phones)
+        return 'unknown';
+    // Per-syllable phones may be parenthesised and stress-digited, e.g. "(s EH)".
+    for (const tok of phones.trim().split(/\s+/)) {
+        const v = tok.replace(/[^A-Za-z]/g, '').toUpperCase(); // strip parens/digits
+        if (ARPABET_VOWELS.has(v))
+            return FREE_VOWELS.has(v) ? 'long' : 'short';
+    }
+    return 'unknown';
+}
+/** Per-syllable vowel lengths for a word, to guide open/closed syllabification. */
+export function syllableVowelLengths(syllables) {
+    return syllables.map(s => {
+        const len = vowelLengthOf(s.phones);
+        const stressed = (s.lexicalStress ?? s.stress ?? 0) >= 1;
+        // Only a *stressed* checked vowel closes its syllable; a reduced/unstressed
+        // syllable stays open (beau·ti·ful, not beau·tif·ul; mem·o·ry, not mem·or·y).
+        if (len === 'short' && !stressed)
+            return 'unknown';
+        return len;
+    });
+}
+/**
+ * Opaque lexicalised compounds whose orthographic syllable boundary the
+ * maximal-onset syllabifier cuts in the wrong place (some·one → so·meone, because
+ * the lone medial 'm' is greedily taken as the onset of syllable 2).  We supply
+ * the morpheme boundary explicitly: the constituents are real words, so each is
+ * syllabified on its own and re-joined.  Applied ONLY when the parts' own
+ * syllable counts sum to the requested count, so a mismatched parse falls through
+ * to the general algorithm rather than mis-splitting.  Display-only (never affects
+ * stress or meter, which derive from the CMU syllable count, not this chunking).
+ */
+const LEXICAL_COMPOUND_PARTS = {
+    someone: ['some', 'one'], anyone: ['any', 'one'], everyone: ['every', 'one'], noone: ['no', 'one'],
+    something: ['some', 'thing'], anything: ['any', 'thing'], everything: ['every', 'thing'], nothing: ['no', 'thing'],
+    somebody: ['some', 'body'], anybody: ['any', 'body'], everybody: ['every', 'body'], nobody: ['no', 'body'],
+    somewhere: ['some', 'where'], anywhere: ['any', 'where'], everywhere: ['every', 'where'], nowhere: ['no', 'where'],
+    somehow: ['some', 'how'], somewhat: ['some', 'what'], someday: ['some', 'day'],
+    sometime: ['some', 'time'], sometimes: ['some', 'times'], someplace: ['some', 'place'],
+    itself: ['it', 'self'], himself: ['him', 'self'], herself: ['her', 'self'], myself: ['my', 'self'],
+    yourself: ['your', 'self'], oneself: ['one', 'self'],
+    themselves: ['them', 'selves'], ourselves: ['our', 'selves'], yourselves: ['your', 'selves'],
+    into: ['in', 'to'], onto: ['on', 'to'], unto: ['un', 'to'], upon: ['up', 'on'],
+    within: ['with', 'in'], without: ['with', 'out'], throughout: ['through', 'out'],
+    cannot: ['can', 'not'], become: ['be', 'come'], became: ['be', 'came'],
+    // Archaic/locative pronominal compounds (frequent in verse).  The medial
+    // silent 'e' of the first element ("where·fore") otherwise inflates the
+    // orthographic vowel-group count and mis-places the boundary.
+    wherefore: ['where', 'fore'], therefore: ['there', 'fore'],
+    wherein: ['where', 'in'], therein: ['there', 'in'], herein: ['here', 'in'],
+    whereby: ['where', 'by'], thereby: ['there', 'by'], hereby: ['here', 'by'],
+    whereof: ['where', 'of'], thereof: ['there', 'of'], hereof: ['here', 'of'],
+    whereto: ['where', 'to'], thereto: ['there', 'to'], hereto: ['here', 'to'],
+    whereon: ['where', 'on'], thereon: ['there', 'on'],
+    whereat: ['where', 'at'], thereat: ['there', 'at'],
+    whereupon: ['where', 'upon'], thereupon: ['there', 'upon'], hereupon: ['here', 'upon'],
+    hereafter: ['here', 'after'], thereafter: ['there', 'after'], whereafter: ['where', 'after'],
+    heretofore: ['here', 'to', 'fore'], hitherto: ['hither', 'to'],
+};
+/** Orthographic syllable estimate for a single sub-word (silent-final-e aware). */
+function quickSyllableCount(s) {
+    const lower = s.toLowerCase();
+    const pos = [];
+    let inV = false;
+    for (let i = 0; i < lower.length; i++) {
+        if (VOWEL_CHARS.has(lower[i])) {
+            if (!inV) {
+                pos.push(i);
+                inV = true;
+            }
+        }
+        else
+            inV = false;
+    }
+    let groups = pos.length;
+    if (groups >= 2 && lower.endsWith('e') && pos[pos.length - 1] === lower.length - 1)
+        groups--;
+    return Math.max(1, groups);
+}
+export function syllabifyWord(word, syllableCount, vowelLengths, morphSuffix) {
+    if (syllableCount <= 1)
+        return [word];
+    // Lexical compound boundary (someone → some·one, not so·meone).  Only when the
+    // constituents' own syllable counts add up to the requested total.
+    {
+        const key = word.toLowerCase().replace(/[^a-z]/g, '');
+        const parts = LEXICAL_COMPOUND_PARTS[key];
+        if (parts && key === word.toLowerCase()) {
+            const counts = parts.map(quickSyllableCount);
+            if (counts.reduce((a, b) => a + b, 0) === syllableCount) {
+                const out = [];
+                let off = 0;
+                for (let p = 0; p < parts.length; p++) {
+                    const seg = word.slice(off, off + parts[p].length);
+                    off += parts[p].length;
+                    out.push(...syllabifyWord(seg, counts[p]));
+                }
+                if (out.length === syllableCount)
+                    return out;
+            }
+        }
+    }
+    // Morpheme-aware peel: when OOV stress assignment validated a productive
+    // archaic suffix (-est/-eth/-ith), split it off as the final syllable so the
+    // stem keeps its spelling (know·est, not kno·west; know·eth, not kno·weth).
+    if (morphSuffix && syllableCount >= 2
+        && word.toLowerCase().endsWith(morphSuffix)
+        && word.length > morphSuffix.length + 1) {
+        const stem = word.slice(0, word.length - morphSuffix.length);
+        const suffixChunk = word.slice(word.length - morphSuffix.length);
+        const stemChunks = syllabifyWord(stem, syllableCount - 1, vowelLengths?.slice(0, syllableCount - 1));
+        return [...stemChunks, suffixChunk];
+    }
+    // For hyphenated words, use hyphen as syllable boundary if counts match
+    if (word.includes('-')) {
+        const parts = word.split('-');
+        if (parts.length === syllableCount) {
+            return parts;
+        }
+    }
+    const cleanWord = word.replace(/-/g, '');
+    if (cleanWord.length <= syllableCount) {
+        if (cleanWord.length === syllableCount)
+            return cleanWord.split('');
+        return [word];
+    }
+    const hyphenMap = [];
+    for (let i = 0; i < word.length; i++) {
+        if (word[i] !== '-')
+            hyphenMap.push(i);
+    }
+    const lower = cleanWord.toLowerCase();
+    const n = lower.length;
+    // Common English consonant digraphs
+    const DIGRAPHS = new Set(['ch', 'sh', 'th', 'wh', 'ph', 'gh', 'ck', 'ng', 'wr', 'kn', 'gn']);
+    // Digraphs that commonly end syllables (codas)
+    const CODA_DIGRAPHS = new Set(['ch', 'sh', 'ck', 'ng', 'th']);
+    // "Muta cum liquida": an obstruent + liquid/glide that, between vowels, stays
+    // together as the onset of the following syllable (maximal-onset principle):
+    // se·cret, be·tween, chil·dren, pro·gram, re·gret.  Deliberately EXCLUDES the
+    // s+stop clusters (st/sp/sc/sk), which in medial position split after a short
+    // vowel (mis·ter, dis·turb, whis·per) rather than maximising the onset.
+    const MEDIAL_ONSET = new Set([
+        'bl', 'br', 'cl', 'cr', 'dr', 'dw', 'fl', 'fr', 'gl', 'gr',
+        'pl', 'pr', 'tr', 'tw',
+    ]);
+    // Legal English 3-consonant onsets (s + voiceless stop + liquid/glide) plus
+    // the orthographic clusters thr/shr/chr/phr/sch (single onset phonemically).
+    const TRIPLE_ONSET = new Set([
+        'str', 'spr', 'scr', 'spl', 'squ', 'thr', 'shr', 'chr', 'phr', 'sch',
+    ]);
+    // Final "consonant + le" forms its own syllable (ta·ble, lit·tle, ap·ple,
+    // tem·ple, bot·tle): the single consonant immediately before "le" joins it.
+    const endsConsonantLe = n >= 3 && lower.endsWith('le') && !VOWEL_CHARS.has(lower[n - 3]);
+    // Non-syllabic past-tense "-ed": the 'e' in a final "…Xed" (X a consonant other
+    // than t/d) is silent (re·turned, not re·tur·ned).  After t/d it IS syllabic
+    // (want·ed, embed·ded), so those are excluded.
+    const endsSilentEd = n >= 3 && lower.endsWith('ed')
+        && !VOWEL_CHARS.has(lower[n - 3]) && lower[n - 3] !== 't' && lower[n - 3] !== 'd';
+    const nuclei = [];
+    let i = 0;
+    while (i < n) {
+        if (VOWEL_CHARS.has(lower[i])) {
+            const vs = i;
+            while (i < n && VOWEL_CHARS.has(lower[i]))
+                i++;
+            const isLoneFinalE = (i === n && (i - vs) === 1 && lower[vs] === 'e');
+            if (isLoneFinalE && nuclei.length >= 2) {
+                // silent-e: a lone 'e' at word end after 2+ nuclei is typically silent
+            }
+            else {
+                nuclei.push({ start: vs, end: i });
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    if (nuclei.length === 0)
+        return [word];
+    // If we have a surplus nucleus and the word ends in a non-syllabic "-ed",
+    // drop that silent 'e' first (preferred over a generic consonant-count merge,
+    // which would otherwise mis-segment e.g. "returned" → "re·tur·ned").
+    if (nuclei.length > syllableCount && endsSilentEd) {
+        const last = nuclei[nuclei.length - 1];
+        if (last.start === n - 2 && last.end === n - 1)
+            nuclei.pop();
+    }
+    while (nuclei.length > syllableCount && nuclei.length > 1) {
+        let minConsonants = Infinity;
+        let mergeIdx = 0;
+        for (let j = 0; j < nuclei.length - 1; j++) {
+            const consonantsBetween = nuclei[j + 1].start - nuclei[j].end;
+            if (consonantsBetween < minConsonants) {
+                minConsonants = consonantsBetween;
+                mergeIdx = j;
+            }
+        }
+        nuclei[mergeIdx] = { start: nuclei[mergeIdx].start, end: nuclei[mergeIdx + 1].end };
+        nuclei.splice(mergeIdx + 1, 1);
+    }
+    const useWord = word;
+    const useN = n;
+    if (nuclei.length === syllableCount) {
+        const boundaries = [0];
+        for (let j = 0; j < nuclei.length - 1; j++) {
+            const gapStart = nuclei[j].end;
+            const gapEnd = nuclei[j + 1].start;
+            const consonants = gapEnd - gapStart;
+            let boundary;
+            if (consonants <= 0) {
+                boundary = gapEnd;
+            }
+            else if (consonants === 1) {
+                // Single intervocalic consonant: Maximal Onset (open, V·CV) by default,
+                // but a checked/short stressed vowel CLOSES the syllable (VC·V):
+                // sev·en / rob·in / lem·on, vs. open e·ven / o·pen / ro·bot after a free
+                // (long) vowel.  Falls back to MOP when vowel length is unknown (OOV).
+                boundary = (vowelLengths && vowelLengths[j] === 'short') ? gapEnd : gapStart;
+            }
+            else if (consonants === 2) {
+                const pair = lower.substring(gapStart, gapEnd);
+                if (MEDIAL_ONSET.has(pair)) {
+                    // Onset cluster (muta cum liquida) normally begins the next syllable
+                    // (ta·ble, se·cret, pro·gram) — UNLESS a checked/short vowel closes the
+                    // syllable, in which case one consonant stays behind (prob·lem, frac·ture).
+                    boundary = (vowelLengths && vowelLengths[j] === 'short') ? gapStart + 1 : gapStart;
+                }
+                else if (DIGRAPHS.has(pair)) {
+                    if (CODA_DIGRAPHS.has(pair)) {
+                        // Common coda: digraph goes with preceding syllable
+                        boundary = gapEnd;
+                    }
+                    else {
+                        // Common onset: digraph goes with following syllable
+                        boundary = gapStart;
+                    }
+                }
+                else {
+                    // Not a cluster/digraph: split (first consonant with prev, second with next)
+                    boundary = gapStart + 1;
+                }
+            }
+            else {
+                // 3+ consonants: maximise the onset — a legal THREE-consonant onset
+                // (s + stop + liquid/glide) carries whole to the next syllable ONLY
+                // when the preceding vowel is known to be long/free (a stressed short
+                // vowel takes the s as its coda: mis·tress, but a free vowel opens:
+                // de·stroy with reduced e).  Else a final 2-consonant onset cluster or
+                // digraph carries; otherwise only the last consonant (chil·dren).
+                const lastThree = lower.substring(gapEnd - 3, gapEnd);
+                const lastTwo = lower.substring(gapEnd - 2, gapEnd);
+                if (TRIPLE_ONSET.has(lastThree) && vowelLengths && vowelLengths[j] === 'long') {
+                    boundary = gapEnd - 3;
+                }
+                else if (MEDIAL_ONSET.has(lastTwo) || DIGRAPHS.has(lastTwo)) {
+                    boundary = gapEnd - 2;
+                }
+                else {
+                    boundary = gapEnd - 1;
+                }
+            }
+            // Final "consonant + le" overrides: the consonant before "le" joins it.
+            if (endsConsonantLe && j === nuclei.length - 2) {
+                boundary = n - 3;
+            }
+            if (boundary >= n)
+                boundary = n - 1;
+            if (boundary <= boundaries[boundaries.length - 1]) {
+                boundary = boundaries[boundaries.length - 1] + 1;
+            }
+            boundaries.push(boundary);
+        }
+        boundaries.push(n);
+        const result = [];
+        for (let j = 0; j < boundaries.length - 1; j++) {
+            const origStart = hyphenMap.length > 0 ? hyphenMap[boundaries[j]] : boundaries[j];
+            const origEnd = hyphenMap.length > 0 ? (boundaries[j + 1] < hyphenMap.length ? hyphenMap[boundaries[j + 1]] : word.length) : boundaries[j + 1];
+            result.push(word.slice(origStart, origEnd));
+        }
+        while (result.length < syllableCount)
+            result.push('');
+        return result.slice(0, syllableCount);
+    }
+    const result = [];
+    let start = 0;
+    for (let s = 0; s < syllableCount - 1; s++) {
+        const remaining = syllableCount - s;
+        const remainingChars = n - start;
+        const idealLen = Math.round(remainingChars / remaining);
+        let end = start + Math.max(2, idealLen);
+        if (end > n - (remaining - 1) * 2)
+            end = n - (remaining - 1) * 2;
+        if (end <= start + 1)
+            end = start + 2;
+        if (end > n)
+            end = n;
+        const origStart = hyphenMap.length > 0 ? hyphenMap[start] : start;
+        const origEnd = hyphenMap.length > 0 ? (end < hyphenMap.length ? hyphenMap[end] : word.length) : end;
+        result.push(word.slice(origStart, origEnd));
+        start = end;
+    }
+    const origStart = hyphenMap.length > 0 ? hyphenMap[start] : start;
+    result.push(word.slice(origStart));
+    while (result.length < syllableCount)
+        result.push('');
+    return result.slice(0, syllableCount);
+}
+/**
+ * Flatten all syllables into display entries with word context.
+ * Each entry carries the original word text, the syllable text
+ * (orthographic chunk), the syllable's position within the word,
+ * and its relative stress level.
+ */
+export function flattenDisplayEntries(words) {
+    const result = [];
+    let globalIdx = 0;
+    let wordIdx = 0;
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass))
+            continue;
+        const sylCount = w.syllables.length;
+        const chunks = syllabifyWord(w.word, sylCount, syllableVowelLengths(w.syllables), w.morphSuffix);
+        for (let si = 0; si < sylCount; si++) {
+            result.push({
+                wordText: w.word,
+                sylText: chunks[si],
+                sylIndex: si,
+                sylCount,
+                relativeStress: w.syllables[si].relativeStress ?? 'w',
+                globalIndex: globalIdx++,
+                wordIndex: wordIdx,
+            });
+        }
+        wordIdx++;
+    }
+    return result;
+}