calliope-ts 0.0.2 → 0.0.4

package/dist/clio/display.js

@@ -0,0 +1,976 @@
+// display.ts — Unified, integrated CLI display for Calliope TS
+// Shows ALL information layers in a single comprehensive view
+import chalk from 'chalk';
+import { isPunctuation } from './parser.js';
+import { syllabifyWord, syllableVowelLengths } from './phonological.js';
+import { computeCaesurae } from './caesura.js';
+import { summarizePoem, analyzePhonopoetics } from './rhyme.js';
+// ═══════════════════════════════════════════════════════════════════════
+// COLOUR SYSTEM — Conceptually motivated palettes
+// ═══════════════════════════════════════════════════════════════════════
+// Lexical stress (numeric 0–3): blue→magenta→red→bold red
+// Represents phonetic prominence from dictionary
+const LEX0 = (s) => chalk.blue(s);
+const LEX1 = (s) => chalk.magenta(s);
+const LEX2 = (s) => chalk.red(s);
+const LEX3 = (s) => chalk.red.bold(s);
+function lexColour(val) {
+    if (val === 0)
+        return LEX0;
+    if (val === 1)
+        return LEX1;
+    if (val === 2)
+        return LEX2;
+    return LEX3;
+}
+// Relative / phonological stress (x w n m s): light-grey→cyan→green→yellow→bright red
+// Represents phonological prominence after phrasal rules.  `x` = zero-provision
+// (maximally-reduced clitic), one rung below the stressless-overt floor `w`.
+// Light grey (not dark blue) so it stays legible on a black terminal.
+const REL_X = (s) => chalk.hex('#b0b0b0')(s);
+const REL_W = (s) => chalk.cyan(s);
+const REL_N = (s) => chalk.green(s);
+const REL_M = (s) => chalk.yellow(s);
+const REL_S = (s) => chalk.redBright(s);
+function relColour(rel) {
+    if (rel === 'x')
+        return REL_X;
+    if (rel === 'w')
+        return REL_W;
+    if (rel === 'n')
+        return REL_N;
+    if (rel === 'm')
+        return REL_M;
+    if (rel === 's')
+        return REL_S;
+    return chalk.gray.dim;
+}
+// Phrasal boundaries — distinct palette (purple/blue/green)
+const B_CP = chalk.magentaBright;
+const B_PP = chalk.blueBright;
+const B_IU = chalk.greenBright;
+const B_CAESURA = chalk.whiteBright.bold; // hard caesura (overt: punctuation / IU edge)
+const B_CAESURA_SOFT = chalk.cyan.dim; // inferred caesura (phonological-phrase pause)
+const B_FOOT = chalk.gray;
+const B_SILENT = chalk.gray.dim;
+// Word roles
+const W_CONTENT = chalk.white;
+const W_FUNCTION = chalk.gray;
+const W_DEP = chalk.italic.dim;
+// Section headers
+const H1 = chalk.bold.underline;
+const H2 = chalk.bold;
+const HR = '─'.repeat(70);
+const HR_THIN = '─'.repeat(50);
+function buildColSyls(words, ius) {
+    const result = [];
+    let globalIdx = 0;
+    for (let iuIdx = 0; iuIdx < ius.length; iuIdx++) {
+        const iu = ius[iuIdx];
+        for (let ppIdx = 0; ppIdx < iu.phonologicalPhrases.length; ppIdx++) {
+            const pp = iu.phonologicalPhrases[ppIdx];
+            for (let cpIdx = 0; cpIdx < pp.cliticGroups.length; cpIdx++) {
+                const cg = pp.cliticGroups[cpIdx];
+                for (let tIdx = 0; tIdx < cg.tokens.length; tIdx++) {
+                    const w = cg.tokens[tIdx];
+                    if (isPunctuation(w.lexicalClass))
+                        continue;
+                    const dep = w.dependency;
+                    const sylCount = w.syllables.length;
+                    const chunks = syllabifyWord(w.word, sylCount, syllableVowelLengths(w.syllables), w.morphSuffix);
+                    for (let si = 0; si < sylCount; si++) {
+                        const syl = w.syllables[si];
+                        const lex = syl.lexicalStress ?? syl.stress;
+                        const rel = syl.relativeStress ?? 'w';
+                        result.push({
+                            chunk: chunks[si] || w.word,
+                            word: w.word,
+                            pos: w.lexicalClass,
+                            isContent: w.isContent,
+                            lexStress: lex,
+                            relStress: rel,
+                            cpId: cpIdx,
+                            ppId: ppIdx,
+                            iuId: iuIdx,
+                            isFirstInWord: si === 0,
+                            isFirstInCP: tIdx === 0 && si === 0,
+                            isFirstInPP: cpIdx === 0 && tIdx === 0 && si === 0,
+                            isFirstInIU: ppIdx === 0 && cpIdx === 0 && tIdx === 0 && si === 0,
+                            isLastInCP: tIdx === cg.tokens.length - 1 && si === sylCount - 1,
+                            isLastInPP: cpIdx === pp.cliticGroups.length - 1 &&
+                                tIdx === cg.tokens.length - 1 && si === sylCount - 1,
+                            isLastInIU: ppIdx === iu.phonologicalPhrases.length - 1 &&
+                                cpIdx === pp.cliticGroups.length - 1 &&
+                                tIdx === cg.tokens.length - 1 && si === sylCount - 1,
+                            depLabel: dep?.dependentType ?? '',
+                            govWord: dep?.governor?.word ?? '',
+                            globalIdx: globalIdx++,
+                            wordRef: w,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// UNIFIED DISPLAY — All layers integrated
+// ═══════════════════════════════════════════════════════════════════════
+export function renderUnifiedDisplay(result, rawLine) {
+    const words = result.sentence.words;
+    const ius = result.phonologicalHierarchy;
+    const detail = result.phonologicalScansion;
+    const colSyls = buildColSyls(words, ius);
+    const lines = [];
+    lines.push('');
+    lines.push(HR);
+    // ── Layer 1: Original text with word-role coloring ──────────────
+    lines.push(H1('Original Text'));
+    lines.push('');
+    const textParts = [];
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass))
+            continue;
+        const wc = w.isContent ? W_CONTENT : W_FUNCTION;
+        const posTag = W_DEP('(' + w.lexicalClass + ')');
+        textParts.push(wc(w.word) + posTag);
+    }
+    lines.push('  ' + textParts.join(' '));
+    lines.push('');
+    // ── Layer 2: Phrasal structure tree ─────────────────────────────
+    lines.push(H1('Phrasal Structure') + '  ' + B_IU('IU') + ' → ' + B_PP('PP') + ' → ' + B_CP('CP'));
+    // Mini-legend: only the POS tags & dependencies that occur in THIS line.
+    lines.push(...renderLineGlossary(words));
+    lines.push('');
+    const wordSet = new Set();
+    const dedupedEntries = [];
+    for (const cs of colSyls) {
+        if (!wordSet.has(cs.wordRef)) {
+            wordSet.add(cs.wordRef);
+            dedupedEntries.push({ col: cs, word: cs.wordRef });
+        }
+    }
+    let lastIU = -1, lastPP = -1;
+    for (const we of dedupedEntries) {
+        const cs = we.col;
+        if (cs.iuId !== lastIU) {
+            lines.push(B_IU('  IU' + (cs.iuId + 1)));
+            lastIU = cs.iuId;
+            lastPP = -1;
+        }
+        if (cs.ppId !== lastPP) {
+            lines.push(B_PP('    PP' + (cs.ppId + 1) + ': {'));
+            lastPP = cs.ppId;
+        }
+        const dep = we.word.dependency;
+        const depInfo = dep && dep.governorIndex > 0
+            ? W_DEP(' ←' + dep.dependentType)
+            : '';
+        const wordLabel = W_CONTENT(we.word.word) + W_DEP('(' + we.word.lexicalClass + ')');
+        lines.push('      ' + B_CP('[') + wordLabel + depInfo + B_CP(']'));
+    }
+    lines.push('    ' + B_PP('}'));
+    lines.push('');
+    // ── Layer 3: Lexical stress (numeric) ───────────────────────────
+    lines.push(H1('Lexical Stress') + '  ' + LEX0('0') + LEX1('1') + LEX2('2') + LEX3('3') + '  (0=none 1=secondary 2=primary 3+=boosted)');
+    lines.push('');
+    const lexParts = [];
+    for (const cs of colSyls) {
+        if (cs.isFirstInWord && cs.globalIdx > 0)
+            lexParts.push(' ');
+        lexParts.push(lexColour(cs.lexStress)(String(cs.lexStress)));
+    }
+    lines.push('  ' + lexParts.join(''));
+    lines.push('');
+    // ── Layer 3b: Phrase stress (McAleese's integer nuclear ramp) ───
+    // The phase that used to be skipped: every word starts at 1; the Compound
+    // Stress Rule pins a compound's subordinate; the Nuclear Stress Rule ramps
+    // the principal stress of each stressed word L→R to the phrase's peak.
+    lines.push(H1('Phrase Stress') + '  ' + chalk.dim('1 = floor (function / compound-subordinate) → N = nuclear peak'));
+    lines.push('');
+    const phrParts = [];
+    for (const cs of colSyls) {
+        if (cs.isFirstInWord && cs.globalIdx > 0)
+            phrParts.push(' ');
+        if (cs.isFirstInWord) {
+            const ps = cs.wordRef.phraseStress || 0;
+            phrParts.push((ps <= 1 ? chalk.dim : chalk.cyanBright)(String(ps)));
+        }
+        else {
+            phrParts.push(' '); // continuation syllable — keep word-start alignment
+        }
+    }
+    lines.push('  ' + phrParts.join(''));
+    lines.push('');
+    // ── Layer 4: Relative stress (w/n/m/s) ──────────────────────────
+    lines.push(H1('Relative Stress') + '  ' + REL_X('x') + REL_W('w') + REL_N('n') + REL_M('m') + REL_S('s') + '  (zero‑provision→weak→low→moderate→strong)');
+    lines.push('');
+    const relParts = [];
+    for (const cs of colSyls) {
+        if (cs.isFirstInWord && cs.globalIdx > 0)
+            relParts.push(' ');
+        relParts.push(relColour(cs.relStress)(cs.relStress));
+    }
+    lines.push('  ' + relParts.join(''));
+    lines.push('');
+    // ── Layer 5: Phonological bracketing ────────────────────────────
+    lines.push(H1('Phonological Bracketing') + '  ' + B_CP('[]') + ' CP  ' + B_PP('{}') + ' PP  ' + B_IU('<>') + ' IU');
+    lines.push('');
+    const sylParts = [];
+    let iuOpen = false, ppOpen = false, cpOpen = false;
+    for (const cs of colSyls) {
+        if (cs.isFirstInIU && !iuOpen) {
+            sylParts.push(B_IU('<'));
+            iuOpen = true;
+        }
+        if (cs.isFirstInPP && !ppOpen) {
+            sylParts.push(B_PP('{'));
+            ppOpen = true;
+        }
+        if (cs.isFirstInCP && !cpOpen) {
+            sylParts.push(B_CP('['));
+            cpOpen = true;
+        }
+        if (cs.isFirstInWord && cs.globalIdx > 0)
+            sylParts.push(' ');
+        sylParts.push(relColour(cs.relStress)(cs.chunk));
+        if (cs.isLastInCP && cpOpen) {
+            sylParts.push(B_CP(']'));
+            cpOpen = false;
+        }
+        if (cs.isLastInPP && ppOpen) {
+            sylParts.push(B_PP('}'));
+            ppOpen = false;
+        }
+        if (cs.isLastInIU && iuOpen) {
+            sylParts.push(B_IU('>'));
+            iuOpen = false;
+        }
+    }
+    lines.push('  ' + sylParts.join(''));
+    lines.push('');
+    // ── Layer 6: Metrical scansion with caesura ─────────────────────
+    lines.push(H1('Metrical Scansion'));
+    lines.push('');
+    const scansion = detail.scansion;
+    const feetRaw = scansion.split('|');
+    const linearSyls = [];
+    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++) {
+            linearSyls.push({
+                chunk: chunks[si] || w.word,
+                relStress: w.syllables[si].relativeStress ?? 'w',
+                wordRef: w,
+            });
+        }
+    }
+    // Caesurae: hard at IU/punctuation breaks, plus one inferred (soft) medial
+    // caesura at a phonological-phrase boundary for a punctuation-free line.
+    const caesurae = computeCaesurae(words, ius, scansion);
+    function isSyllableChar(ch) {
+        return 'xXwWnNmMsS'.includes(ch);
+    }
+    let sylIdx = 0;
+    const footDisplays = [];
+    let prevWordRef = null;
+    for (const rawFoot of feetRaw) {
+        let footOut = '';
+        for (const ch of rawFoot) {
+            if (ch === '-') {
+                footOut += B_SILENT('·');
+                continue;
+            }
+            if (!isSyllableChar(ch))
+                continue;
+            if (sylIdx < linearSyls.length) {
+                const ls = linearSyls[sylIdx];
+                if (prevWordRef !== null && ls.wordRef !== prevWordRef)
+                    footOut += ' ';
+                footOut += relColour(ls.relStress)(ls.chunk);
+                prevWordRef = ls.wordRef;
+                sylIdx++;
+            }
+        }
+        const ck = caesurae.get(sylIdx);
+        if (ck)
+            footOut += ' ' + caesuraGlyph(ck);
+        footDisplays.push(footOut);
+    }
+    lines.push('  ' + H2('Feet:   ') + footDisplays.join(B_FOOT(' | ')));
+    const stressDisplays = [];
+    let rIdx = 0;
+    for (const rawFoot of feetRaw) {
+        let s = '';
+        for (const ch of rawFoot) {
+            if (ch === '-') {
+                s += B_SILENT('_');
+                continue;
+            }
+            if (!isSyllableChar(ch))
+                continue;
+            if (rIdx < linearSyls.length) {
+                s += relColour(linearSyls[rIdx].relStress)(linearSyls[rIdx].relStress);
+                rIdx++;
+            }
+        }
+        const ck2 = caesurae.get(rIdx);
+        if (ck2)
+            s += ' ' + caesuraGlyph(ck2);
+        stressDisplays.push(s);
+    }
+    lines.push('  ' + H2('Stress: ') + stressDisplays.join(B_FOOT(' | ')));
+    lines.push('');
+    // ── Layer 7: Dependencies ───────────────────────────────────────
+    lines.push(H1('Dependencies'));
+    lines.push('');
+    for (const we of dedupedEntries) {
+        const w = we.word;
+        if (isPunctuation(w.lexicalClass))
+            continue;
+        const dep = w.dependency;
+        if (!dep)
+            continue;
+        if (dep.governorIndex === 0 || dep.dependentType === 'root') {
+            lines.push('  ' + B_IU('ROOT →') + ' ' + W_CONTENT(w.word));
+        }
+        else {
+            lines.push('  ' +
+                W_FUNCTION(w.word.padEnd(12)) +
+                W_DEP('←' + dep.dependentType + '← ') +
+                W_CONTENT(dep.governorName));
+        }
+    }
+    lines.push('');
+    // ── Layer 8: Summary ────────────────────────────────────────────
+    lines.push(H1('Summary'));
+    lines.push('');
+    lines.push('  ' + H2('Meter:    ') + detail.meter + chalk.dim('  (' + detail.footCount + ' feet)') + consensusNote(detail) + rhythmNoteStr(detail));
+    const rank = formatRanking(detail.ranking);
+    lines.push('  ' + H2('Fit:      ') + chalk.yellow(detail.certainty + '%') + (rank ? '   ' + rank : ''));
+    lines.push('  ' + H2('Scansion: ') + detail.scansion);
+    lines.push('  ' + H2('Summary:  ') + detail.summary);
+    lines.push('');
+    // ── Layer 9: Scandroid comparison (if available) ────────────────
+    if (result.scandroidCorral || result.scandroidMaximise) {
+        lines.push(H1('Scandroid Comparison'));
+        lines.push('');
+        if (result.scandroidCorral) {
+            lines.push('  ' + H2('CW: ') + result.scandroidCorral.scansion);
+        }
+        if (result.scandroidMaximise) {
+            lines.push('  ' + H2('MN: ') + result.scandroidMaximise.scansion);
+        }
+        lines.push('');
+    }
+    // ── Layer 10: Reading projection (stress gradient over the input) ──
+    // A reading-view-style colourisation of the verbatim input, so the finalised
+    // analysis always shows "something that looks like the input".  Falls back to
+    // the parsed surface forms when the raw line wasn't supplied.
+    lines.push(H1('Reading Projection') + chalk.dim('  — stress gradient over the input'));
+    lines.push('');
+    const projection = rawLine && rawLine.trim()
+        ? projectStressOntoLine(rawLine, words)
+        : words.filter(w => !isPunctuation(w.lexicalClass)).map(w => colourToken(w.word, w)).join(' ');
+    lines.push('  ' + projection);
+    lines.push('');
+    // ── Layer 11: Legend ────────────────────────────────────────────
+    lines.push(HR_THIN);
+    lines.push(renderLegend());
+    lines.push(HR);
+    return lines.join('\n');
+}
+// ═══════════════════════════════════════════════════════════════════════
+// LEGEND
+// ═══════════════════════════════════════════════════════════════════════
+export function renderLegend() {
+    return [
+        H2('Legend'),
+        '  ' + B_CP('[]') + ' Clitic Phrase  ' + B_PP('{}') + ' Phonological Phrase  ' + B_IU('<>') + ' Intonational Unit',
+        '  ' + LEX0('0') + LEX1('1') + LEX2('2') + LEX3('3') + '  Lexical stress (0=none 1=secondary 2=primary 3+=boosted)',
+        '  ' + REL_X('x') + REL_W('w') + REL_N('n') + REL_M('m') + REL_S('s') + '  Relative stress (zero‑provision→weak→low→moderate→strong)',
+        '  ' + W_CONTENT('content') + '  ' + W_FUNCTION('function') + '  Word class',
+        '  ' + B_CAESURA('‖') + ' Caesura (phrasal break)  ' + B_CAESURA_SOFT('¦') + ' Inferred caesura  ' +
+            B_FOOT('|') + ' Foot boundary  ' + B_SILENT('·') + ' Silent beat',
+    ].join('\n');
+}
+// Penn Treebank POS tags that FinNLP's en-pos tagger assigns to words (the tags
+// shown as "(TAG)" in the Original Text / Phrasal Structure layers).  Pure
+// punctuation/symbol/list tags (, : . ( ) # $ SYM LS) are intentionally omitted —
+// they label no lexical word in the prosodic analysis.  Grouped by word class so
+// the distinctions read clearly.
+const POS_GROUPS = [
+    { label: 'Nouns', tags: [
+            ['NN', { name: 'noun, singular or mass', eg: 'table, water, dust' }],
+            ['NNS', { name: 'noun, plural', eg: 'tables, waters' }],
+            ['NNP', { name: 'proper noun, singular', eg: 'London, Pound' }],
+            ['NNPS', { name: 'proper noun, plural', eg: 'Americans, Smiths' }],
+        ] },
+    { label: 'Verbs & modals', tags: [
+            ['VB', { name: 'verb, base form', eg: 'throw, eat, run' }],
+            ['VBD', { name: 'verb, past tense', eg: 'threw, ate, ran' }],
+            ['VBG', { name: 'verb, gerund / present part.', eg: 'throwing, eating' }],
+            ['VBN', { name: 'verb, past participle', eg: 'thrown, eaten' }],
+            ['VBP', { name: 'verb, non-3rd-sg present', eg: '(I) throw, run' }],
+            ['VBZ', { name: 'verb, 3rd-sg present', eg: 'throws, runs' }],
+            ['MD', { name: 'modal', eg: 'can, will, must' }],
+        ] },
+    { label: 'Adjectives & adverbs', tags: [
+            ['JJ', { name: 'adjective', eg: 'green, large' }],
+            ['JJR', { name: 'adjective, comparative', eg: 'greener, larger' }],
+            ['JJS', { name: 'adjective, superlative', eg: 'greenest, largest' }],
+            ['RB', { name: 'adverb', eg: 'quickly, very' }],
+            ['RBR', { name: 'adverb, comparative', eg: 'faster, better' }],
+            ['RBS', { name: 'adverb, superlative', eg: 'fastest, best' }],
+        ] },
+    { label: 'Determiners & numbers', tags: [
+            ['DT', { name: 'determiner', eg: 'the, a, an' }],
+            ['PDT', { name: 'predeterminer', eg: 'all (the books), both' }],
+            ['CD', { name: 'cardinal number', eg: 'one, two, three' }],
+        ] },
+    { label: 'Pronouns', tags: [
+            ['PRP', { name: 'personal pronoun', eg: 'I, you, he, they' }],
+            ['PRP$', { name: 'possessive pronoun', eg: 'my, your, their' }],
+        ] },
+    { label: 'Wh-words', tags: [
+            ['WDT', { name: 'wh-determiner', eg: 'which, that' }],
+            ['WP', { name: 'wh-pronoun', eg: 'who, what' }],
+            ['WP$', { name: 'possessive wh-pronoun', eg: 'whose' }],
+            ['WRB', { name: 'wh-adverb', eg: 'when, where, why' }],
+        ] },
+    { label: 'Function & other', tags: [
+            ['IN', { name: 'preposition / subord. conj.', eg: 'in, of, although' }],
+            ['TO', { name: 'infinitival "to"', eg: 'to (go)' }],
+            ['CC', { name: 'coordinating conjunction', eg: 'and, but, or' }],
+            ['RP', { name: 'particle', eg: 'up (give up), off' }],
+            ['EX', { name: 'existential "there"', eg: 'there (is)' }],
+            ['POS', { name: 'possessive ending', eg: "'s, '" }],
+            ['UH', { name: 'interjection', eg: 'oh, wow, ah' }],
+            ['FW', { name: 'foreign word', eg: 'je ne sais quoi' }],
+        ] },
+];
+// Grammatical dependency relations AS THE TOOLKIT DISPLAYS THEM (the lowercase
+// labels shown as "←label", after FinNLP's relations are mapped to the
+// Antelope/Universal-Dependencies scheme in parser.ts).  Grouped by role.
+const DEP_GROUPS = [
+    { label: 'Core arguments', deps: [
+            ['nsubj', { name: 'nominal subject', eg: 'I like you' }],
+            ['nsubjpass', { name: 'nominal subject (passive)', eg: 'I was given a chance' }],
+            ['dobj', { name: 'direct object', eg: 'I like you' }],
+            ['iobj', { name: 'indirect object', eg: 'she gave me a book' }],
+            ['pobj', { name: 'object of preposition (oblique)', eg: 'to the children' }],
+        ] },
+    { label: 'Clausal relations', deps: [
+            ['ccomp', { name: 'clausal complement', eg: 'ordered to dig' }],
+            ['xcomp', { name: 'open clausal complement', eg: 'told us to dig' }],
+            ['advcl', { name: 'adverbial clause modifier', eg: 'walking as rain fell' }],
+            ['acl', { name: 'clausal modifier of a noun', eg: 'the man you love' }],
+        ] },
+    { label: 'Modifiers', deps: [
+            ['amod', { name: 'adjectival modifier', eg: 'good to him' }],
+            ['advmod', { name: 'adverbial modifier', eg: 'genetically modified' }],
+            ['nummod', { name: 'numeric modifier', eg: '2 eggs' }],
+            ['nmod', { name: 'nominal modifier', eg: 'news of the market' }],
+            ['poss', { name: 'possessive / nominal mod.', eg: "Senka's match" }],
+            ['det', { name: 'determiner', eg: 'the book' }],
+        ] },
+    { label: 'Function & markers', deps: [
+            ['prep', { name: 'case / preposition marker', eg: 'went to Rome' }],
+            ['aux', { name: 'auxiliary', eg: 'am going' }],
+            ['auxpass', { name: 'auxiliary (passive)', eg: 'have been marked' }],
+            ['cc', { name: 'coordinating conjunction', eg: 'Matt and Alex' }],
+            ['mark', { name: 'clause / complement marker', eg: 'if I like it' }],
+            ['prt', { name: 'verb particle', eg: 'switched it off' }],
+            ['expl', { name: 'expletive', eg: 'there is' }],
+            ['discourse', { name: 'discourse element', eg: 'I like that :)' }],
+            ['intj', { name: 'interjection', eg: 'pass it, please' }],
+        ] },
+    { label: 'Other', deps: [
+            ['root', { name: 'root (head of the sentence)', eg: 'the main predicate' }],
+            ['dep', { name: 'unspecified dependency', eg: '(unresolved)' }],
+            ['punct', { name: 'punctuation', eg: 'Guys, calm!' }],
+        ] },
+];
+// Flat lookups (used by the per-line mini-legend).
+const POS_GLOSS = Object.fromEntries(POS_GROUPS.flatMap(g => g.tags));
+const DEP_GLOSS = Object.fromEntries(DEP_GROUPS.flatMap(g => g.deps));
+/** A glossary row, padded on the RAW strings (so chalk colour codes don't skew
+ *  alignment).  `tagWidth` is sized to the widest tag in the table. */
+function glossRow(tag, g, tagWidth) {
+    return '  ' + chalk.cyan(tag.padEnd(tagWidth)) + W_CONTENT(g.name.padEnd(32)) + chalk.dim('e.g. ' + g.eg);
+}
+/**
+ * The long-form legend triggered from the main menu's "Display Legend" option:
+ * the compact legend PLUS full Penn POS-tag and grammatical-dependency glossaries.
+ * (These glossaries are deliberately NOT part of the compact in-output legend.)
+ */
+export function renderFullLegend() {
+    const out = [];
+    out.push(renderLegend());
+    out.push('');
+    out.push(HR_THIN);
+    out.push(H1('Part-of-Speech Tags') + chalk.dim('  — Penn Treebank, as tagged by en-pos'));
+    const posWidth = Math.max(...POS_GROUPS.flatMap(g => g.tags.map(([t]) => t.length))) + 2;
+    for (const grp of POS_GROUPS) {
+        out.push('');
+        out.push('  ' + H2(grp.label));
+        for (const [tag, g] of grp.tags)
+            out.push(glossRow(tag, g, posWidth));
+    }
+    out.push('');
+    out.push(HR_THIN);
+    out.push(H1('Grammatical Dependencies') + chalk.dim('  — relation of each word to its governor (←label)'));
+    const depWidth = Math.max(...DEP_GROUPS.flatMap(g => g.deps.map(([d]) => d.length))) + 2;
+    for (const grp of DEP_GROUPS) {
+        out.push('');
+        out.push('  ' + H2(grp.label));
+        for (const [dep, g] of grp.deps)
+            out.push(glossRow(dep, g, depWidth));
+    }
+    return out.join('\n');
+}
+/**
+ * A compact per-line mini-legend: only the POS tags and dependency relations that
+ * actually occur in THIS line's parse, defined briefly (no examples), for the head
+ * of the detailed view's Phrasal Structure section.  Fits in one or two lines.
+ */
+function renderLineGlossary(words) {
+    const posSeen = [];
+    const depSeen = [];
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass))
+            continue;
+        if (!posSeen.includes(w.lexicalClass))
+            posSeen.push(w.lexicalClass);
+        const dep = w.dependency;
+        if (dep && dep.governorIndex > 0 && dep.dependentType && !depSeen.includes(dep.dependentType)) {
+            depSeen.push(dep.dependentType);
+        }
+    }
+    // Concise gloss for the mini-legend: drop the comma/parenthesis qualifier that
+    // the full legend carries ("noun, singular or mass" → "noun").
+    const brief = (name) => name.split(/,| \(/)[0].trim();
+    const out = [];
+    if (posSeen.length) {
+        const items = posSeen.map(t => chalk.cyan(t) + chalk.dim('=') + W_FUNCTION(brief(POS_GLOSS[t]?.name ?? t)));
+        out.push('  ' + chalk.dim('PoS  ') + items.join(chalk.dim(' · ')));
+    }
+    if (depSeen.length) {
+        const items = depSeen.map(d => chalk.cyan(d) + chalk.dim('=') + W_FUNCTION(brief(DEP_GLOSS[d]?.name ?? d)));
+        out.push('  ' + chalk.dim('Dep  ') + items.join(chalk.dim(' · ')));
+    }
+    return out;
+}
+/** Surface form reduced to bare lowercase letters (drops apostrophes/hyphens). */
+function normWordForm(s) {
+    return s.toLowerCase().replace(/[^a-z]/g, '');
+}
+/** Colour each orthographic syllable of an original token by its relative stress. */
+function colourToken(tokenText, word) {
+    const sylCount = Math.max(1, word.syllables.length);
+    const chunks = syllabifyWord(tokenText, sylCount, syllableVowelLengths(word.syllables), word.morphSuffix); // partitions the WHOLE token
+    const stresses = chunks.map((_, i) => word.syllables[i]?.relativeStress ?? 'w');
+    // Fast path: chunks reconstruct the token exactly (the common case).
+    if (chunks.join('') === tokenText) {
+        return chunks.map((c, i) => relColour(stresses[i])(c)).join('');
+    }
+    // Fallback: the syllabifier dropped a delimiter (it strips hyphens), so walk
+    // the ORIGINAL token char-by-char, assigning each kept char to its syllable
+    // by the chunk lengths and emitting dropped hyphens verbatim.  Every original
+    // character is emitted exactly once, so nothing is ever lost.
+    const lens = chunks.map(c => c.length);
+    let out = '';
+    let ci = 0;
+    let consumed = 0;
+    for (const ch of tokenText) {
+        if (ch === '-') {
+            out += ch;
+            continue;
+        } // dropped delimiter, verbatim
+        while (ci < lens.length - 1 && consumed >= lens[ci]) {
+            ci++;
+            consumed = 0;
+        }
+        out += relColour(stresses[ci])(ch);
+        consumed++;
+    }
+    return out;
+}
+/**
+ * Project per-syllable stress colours back onto the original line, preserving
+ * capitalisation, punctuation, spacing and any extrametrical fragments the
+ * pipeline dropped (e.g. possessive "'s").  Word-like tokens are coloured;
+ * everything between them (spaces, punctuation, dashes) is emitted verbatim.
+ *
+ * Alignment is tolerant: it matches each token to the next parsed word by
+ * normalised form (equal, or token starts with the word — handling "cat's"),
+ * with a small look-ahead resync so a stray/unsyllabified token never derails
+ * the rest of the line.  No original character is ever dropped.
+ */
+export function projectStressOntoLine(rawLine, words) {
+    const tokenRe = /[A-Za-z]+(?:['’\-][A-Za-z]+)*/g;
+    let out = '';
+    let cursor = 0;
+    let wi = 0;
+    let m;
+    while ((m = tokenRe.exec(rawLine)) !== null) {
+        const start = m.index;
+        const end = start + m[0].length;
+        out += rawLine.slice(cursor, start); // gap text, verbatim
+        cursor = end;
+        const token = m[0];
+        const tokNorm = normWordForm(token);
+        const matches = (w) => {
+            if (!w)
+                return false;
+            const wn = normWordForm(w.word);
+            return wn.length > 0 && (tokNorm === wn || tokNorm.startsWith(wn));
+        };
+        if (matches(words[wi])) {
+            out += colourToken(token, words[wi]);
+            wi++;
+        }
+        else {
+            // Resync: a parsed word may have been skipped (e.g. unsyllabified "'s").
+            let found = -1;
+            for (let k = wi; k < Math.min(words.length, wi + 4); k++) {
+                if (matches(words[k])) {
+                    found = k;
+                    break;
+                }
+            }
+            if (found >= 0) {
+                out += colourToken(token, words[found]);
+                wi = found + 1;
+            }
+            else {
+                out += token; // leave verbatim; do not advance the word cursor
+            }
+        }
+    }
+    out += rawLine.slice(cursor); // trailing text, verbatim
+    return out;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// CAESURA RENDERING  (placement logic now lives in caesura.ts)
+// ═══════════════════════════════════════════════════════════════════════
+/** Render the glyph for a caesura kind. */
+function caesuraGlyph(kind) {
+    return kind === 'hard' ? B_CAESURA('‖') : B_CAESURA_SOFT('¦');
+}
+/** Colour a scansion string ("nws|nns|-wns") letter-by-letter, inserting caesura
+ *  marks (at foot boundaries) when a caesura map is supplied. */
+function colourScansionMap(scansion, caesurae) {
+    let out = '';
+    let sc = 0; // syllables emitted so far
+    const emitted = new Set();
+    const caesAt = () => {
+        if (caesurae && caesurae.has(sc) && !emitted.has(sc)) {
+            emitted.add(sc);
+            return ' ' + caesuraGlyph(caesurae.get(sc)) + ' ';
+        }
+        return '';
+    };
+    for (const ch of scansion) {
+        if (ch === '|') {
+            const c = caesAt();
+            out += c || B_FOOT('|');
+        }
+        else if (ch === '-') {
+            out += B_SILENT('-');
+        }
+        else if ('xwnms'.includes(ch)) {
+            out += caesAt(); // a (rare) mid-foot caesura, inserted inline
+            out += relColour(ch)(ch);
+            sc++;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+const METER_ABBR = {
+    iambic: 'iamb', trochaic: 'troch', anapestic: 'anap', dactylic: 'dact',
+    amphibrachic: 'amph', bacchic: 'bacch', spondaic: 'spon', pyrrhic: 'pyrr',
+    'free verse': 'free',
+};
+// ── Meter-family colours ───────────────────────────────────────────
+// One consistent, legible LIGHT tone per metre family, reused EVERYWHERE a
+// metre is named (the reading per-line meter, the top-3 ranking, and the
+// synopsis).  The foot-count label (pentameter / octameter…) stays white — we
+// tint only the family word, so the output is informative without being gaudy.
+const METER_HUE = {
+    iambic: chalk.hex('#7fb8ff'), // light blue
+    trochaic: chalk.hex('#ffc24d'), // yellow / orange
+    dactylic: chalk.hex('#88e0a0'), // mid / light green
+    amphibrachic: chalk.hex('#ff9ec4'), // pinkish
+    anapestic: chalk.hex('#ff7a6b'), // reddish
+    bacchic: chalk.hex('#c08be6'), // purple / wine
+    spondaic: chalk.hex('#b8b8b8'),
+    pyrrhic: chalk.hex('#b8b8b8'),
+};
+const METER_FALLBACK = chalk.hex('#cfd8e3'); // free verse / unknown
+/** Tint a metre-family WORD (the first token of a metre name) by its hue. */
+function meterFamilyColour(family) {
+    return METER_HUE[family.toLowerCase()] ?? METER_FALLBACK;
+}
+/** Colour a full metre label ("iambic pentameter"): family tinted, foot-count
+ *  label left white.  Bare "free verse" / multi-word non-families: fallback. */
+function colourMeterLabel(meter) {
+    const sp = meter.indexOf(' ');
+    if (sp < 0)
+        return meterFamilyColour(meter)(meter);
+    const family = meter.slice(0, sp);
+    const hue = METER_HUE[family.toLowerCase()];
+    if (!hue)
+        return METER_FALLBACK(meter);
+    return hue(family) + chalk.whiteBright(meter.slice(sp));
+}
+/** Tint every metre-family word/abbreviation occurring inside a free-form
+ *  string (used to colour the synopsis values without restructuring them).
+ *  Longest-first so "iamb" inside "iambic" is not matched before the full word. */
+const _METER_WORD_RE = /\b(iambic|trochaic|dactylic|amphibrachic|anapestic|bacchic|spondaic|pyrrhic|iamb|troch|dact|amph|anap|bacch|spon|pyrr)\b/gi;
+function tintMeterNames(s) {
+    return s.replace(_METER_WORD_RE, (w) => {
+        const key = w.toLowerCase();
+        const fam = key.startsWith('iamb') ? 'iambic' : key.startsWith('troch') ? 'trochaic'
+            : key.startsWith('dact') ? 'dactylic' : key.startsWith('amph') ? 'amphibrachic'
+                : key.startsWith('anap') ? 'anapestic' : key.startsWith('bacch') ? 'bacchic'
+                    : key.startsWith('spon') ? 'spondaic' : 'pyrrhic';
+        return meterFamilyColour(fam)(w);
+    });
+}
+/** Compact top-3 meter fit scores, e.g. "anap 0.81 · iamb 0.77 · amph 0.74" —
+ *  each family abbreviation tinted its hue, the score dimmed, no enclosing
+ *  parentheses (set off from the meter name by a dim "|" at the call site). */
+function formatRanking(ranking) {
+    if (!ranking || ranking.length === 0)
+        return '';
+    const top = ranking.slice(0, 3).map(r => meterFamilyColour(r.meter)(METER_ABBR[r.meter] ?? r.meter) + chalk.dim(' ' + r.score.toFixed(2)));
+    return top.join(chalk.dim(' · '));
+}
+/** Divergence notes.  After the continuity rename, a near-tie line's BASE
+ *  meter is already the stanza/poem-dominant one and `standaloneMeter` records
+ *  the numerically-best standalone reading ("≈ continuity; standalone:
+ *  dactylic tetrameter").  `consensusMeter` survives only when the forced
+ *  re-fit failed — then the old "aligns w/" annotation still applies. */
+function consensusNote(detail) {
+    if (detail.standaloneMeter) {
+        return chalk.dim.italic(`  ≈ continuity; standalone: ${detail.standaloneMeter}`);
+    }
+    if (!detail.consensusMeter)
+        return '';
+    return chalk.dim.italic(`  ↔ aligns w/ stanza ${detail.consensusMeter}`);
+}
+/** Non-classical rhythm annotation (dolnik / taktovik / accentual), set by the
+ *  rhythm layer.  Shown as a separate chip AFTER the meter — it supplements the
+ *  classical reading (in beats), it never replaces it. */
+function rhythmNoteStr(detail) {
+    if (!detail.rhythmNote)
+        return '';
+    const note = detail.rhythmNote;
+    // Some notes (the 4/3 accentual) already carry a ♪; don't double it.
+    return chalk.magenta.dim('  ' + (note.includes('♪') ? note : '♪ ' + note));
+}
+/** Rhyme chip for a line: the end-rhyme scheme letter with its rhyme TYPE
+ *  (e.g. "A(perfect)"; '·' = unrhymed), PLUS any pre-caesural INTERNAL rhymes,
+ *  each parenthesised and cyan with its own type, shown before the end letter:
+ *  e.g. "(C)(perfect) A(perfect)". */
+function rhymeStr(detail) {
+    const r = detail.rhyme;
+    if (!r)
+        return '';
+    const parts = [];
+    for (const iw of r.internal ?? []) {
+        parts.push(chalk.cyan(`(${iw.letter})`) + (iw.type ? chalk.dim(`(${iw.type})`) : ''));
+    }
+    if (r.letter && r.letter !== '·') {
+        parts.push(chalk.yellowBright(r.letter) + (r.type ? chalk.dim(`(${r.type})`) : ''));
+    }
+    else if (parts.length === 0) {
+        parts.push(chalk.dim('·'));
+    }
+    return '  ' + parts.join(' ');
+}
+/** Non-punctuation, syllable-bearing words across all of a line's sentences. */
+function collectLineWords(ln) {
+    const ws = [];
+    for (const res of ln.results) {
+        for (const w of res.sentence.words) {
+            if (!isPunctuation(w.lexicalClass) && w.syllables.length > 0)
+                ws.push(w);
+        }
+    }
+    return ws;
+}
+/**
+ * The Phonopoetics block of the synopsis: end / caesural / head rhymes (each
+ * letter coloured by the strongest relative-stress tier it spans), alliteration,
+ * and acrostics.  Only subsections actually present in the poem are shown.
+ */
+function renderPhonopoetics(p) {
+    // a rhyme pair "word [A|L1(|kind)] -> word [A|L4]", letter tinted by top stress
+    const rel = (r) => {
+        const L = relColour(r.topStress)(r.letter);
+        const D = chalk.dim;
+        const kindTag = r.kind === 'end' ? '' : D('|' + r.kind);
+        const typ = r.type ? D(` ${r.type}`) : '';
+        return chalk.white(r.fromWord) + ' ' + D('[') + L + D('|') + D(r.fromLabel) + kindTag + D(']')
+            + D(' → ') + chalk.white(r.toWord) + ' ' + D('[') + L + D('|') + D(r.toLabel) + D(']') + typ;
+    };
+    const SEP = chalk.dim('  ·  ');
+    const sub = [];
+    if (p.end.length)
+        sub.push({ label: 'End-Rhymes', body: p.end.map(rel).join(SEP) });
+    if (p.caesural.length)
+        sub.push({ label: 'Caesural Rhymes', body: p.caesural.map(rel).join(SEP) });
+    if (p.head.length)
+        sub.push({ label: 'Head Rhymes', body: p.head.map(rel).join(SEP) });
+    if (p.alliteration.length)
+        sub.push({
+            label: 'Alliteration',
+            body: p.alliteration.map(a => chalk.white(a.words.join(' ')) + chalk.dim(` (${a.label})`)).join(SEP),
+        });
+    if (p.acrostics.length)
+        sub.push({
+            label: 'Acrostic',
+            body: p.acrostics.map(a => a.firsts.map((f, i) => chalk.dim('[' + a.labels[i] + ':') + chalk.whiteBright(f) + chalk.dim(']')).join('')
+                + chalk.dim(' → ') + chalk.yellowBright(a.word)).join(SEP),
+        });
+    if (sub.length === 0)
+        return [];
+    const out = ['', chalk.bold.cyan('Phonopoetics:')];
+    const w = Math.max(...sub.map(s => s.label.length)) + 2;
+    for (const s of sub)
+        out.push('  ' + chalk.bold((s.label + ':').padEnd(w)) + s.body);
+    return out;
+}
+/**
+ * Reading view: the poem itself in its original formatting, each syllable
+ * coloured by 4-tier relative stress, followed by a same-structure block of
+ * per-line stress maps + meter (with top-3 fit scores).  This is the whole
+ * output for this mode — not the full per-line analytic dump.
+ */
+/** A verse line CLOSED by terminal or clause punctuation is END-STOPPED (a
+ *  prosodic pause at the line break); one ending on a word with no boundary
+ *  punctuation RUNS ON — enjambment — its intonational unit spilling into the
+ *  next line.  (Trailing quotes/brackets are ignored when judging the close.) */
+function lineRunsOn(raw) {
+    const t = raw.replace(/["'’”»)\]]+$/, '').trimEnd();
+    if (!t)
+        return false;
+    return !/[.!?;:,—–…]$/.test(t);
+}
+/** Poem-wide enjambment summary (end-stopped vs run-on line-ends), or null for
+ *  a single line.  The final line is terminal by position, so only the
+ *  line-INTERNAL breaks (lines 1..n-1) are judged. */
+function summariseEnjambment(stanzas) {
+    const raws = stanzas.flatMap(st => st.lines.map(l => l.raw));
+    if (raws.length < 2)
+        return null;
+    const interior = raws.slice(0, -1);
+    const enjambed = [];
+    interior.forEach((r, i) => { if (lineRunsOn(r))
+        enjambed.push(i + 1); });
+    const n = interior.length, k = enjambed.length;
+    if (k === 0)
+        return 'end-stopped throughout';
+    const where = k <= 6 ? ' (lines ' + enjambed.join(', ') + ')' : '';
+    return k >= Math.ceil(n / 2)
+        ? `predominantly enjambed — ${k} of ${n} line-ends run on${where}`
+        : `mostly end-stopped — ${k} of ${n} line-ends enjambed${where}`;
+}
+export function renderReadingView(stanzas) {
+    const out = [];
+    const multiStanza = stanzas.length > 1;
+    out.push('');
+    out.push(HR);
+    out.push(H1('Reading View') + chalk.dim('  — stress gradient over input text'));
+    out.push('');
+    // ── Block 1: the poem, original formatting, syllables coloured ──
+    // Multi-stanza poems get a right-aligned "Stanza N" counter in the blank line
+    // before each stanza after the first (the gaps between stanzas).
+    for (let s = 0; s < stanzas.length; s++) {
+        if (multiStanza && s > 0) {
+            out.push('');
+            out.push(chalk.dim.italic(('Stanza ' + (s + 1)).padStart(HR.length)));
+        }
+        for (const ln of stanzas[s].lines) {
+            out.push(projectStressOntoLine(ln.raw, collectLineWords(ln)));
+        }
+    }
+    out.push('');
+    out.push(HR_THIN);
+    out.push(H1('Stress Maps, Meter, & Rhymes') + chalk.dim('  — top-3 fit scores per line'));
+    out.push('');
+    // ── Block 2: stress maps + meter, same stanza/line structure ──
+    for (let s = 0; s < stanzas.length; s++) {
+        const firstDetail = stanzas[s].lines.flatMap(l => l.results)[0]?.phonologicalScansion;
+        const formNote = firstDetail?.formNote ? chalk.green.dim('  ❡ ' + firstDetail.formNote) : '';
+        if (multiStanza)
+            out.push(H2('Stanza ' + (s + 1)) + formNote);
+        else if (formNote)
+            out.push(formNote.trim());
+        for (let l = 0; l < stanzas[s].lines.length; l++) {
+            const ln = stanzas[s].lines[l];
+            const baseLabel = multiStanza ? `S${s + 1}L${l + 1}` : `L${l + 1}`;
+            if (ln.results.length === 0) {
+                out.push('  ' + chalk.dim(baseLabel.padEnd(8) + '(no parse)'));
+                continue;
+            }
+            for (let r = 0; r < ln.results.length; r++) {
+                const res = ln.results[r];
+                const d = res.phonologicalScansion;
+                const label = ln.results.length > 1 ? `${baseLabel}.${r + 1}` : baseLabel;
+                const caesurae = computeCaesurae(res.sentence.words, res.phonologicalHierarchy, d.scansion);
+                const map = colourScansionMap(d.scansion, caesurae);
+                const rank = formatRanking(d.ranking);
+                out.push('  ' + chalk.bold(label.padEnd(8)) + map + '  ' +
+                    colourMeterLabel(d.meter) + (rank ? chalk.dim(' | ') + rank : '') + consensusNote(d) + rhythmNoteStr(d) + rhymeStr(d));
+            }
+        }
+        if (multiStanza && s < stanzas.length - 1)
+            out.push('');
+    }
+    // ── Block 3: Legend ──
+    // Kept ABOVE the synopsis: the legend serves the Stress Maps & Meter, and the
+    // Phonopoetics subsection of the synopsis below can run long — left at the
+    // bottom it gets pushed out of the field of view.
+    out.push('');
+    out.push(HR_THIN);
+    out.push(renderLegend());
+    // ── Block 4: cumulative poem synopsis (non-interfering meta-measure) ──
+    // Several top conclusions about the poem as a whole, drawn only from the
+    // per-line determinations above — never overriding any of them.
+    const synopsis = summarizePoem(stanzas.map(st => st.lines.flatMap(l => l.results)));
+    if (synopsis.length > 0) {
+        out.push('');
+        out.push(HR_THIN);
+        out.push(H1('Poem Synopsis') + chalk.dim(' In short, we have:'));
+        out.push('');
+        const w = Math.max(...synopsis.map(r => r.label.length)) + 2;
+        for (const row of synopsis) {
+            const label = chalk.bold.cyan((row.label + ':').padEnd(w));
+            // Colour the value so the block is not a wall of white: tint any metre
+            // names their family hue, and highlight the mean-fit %.
+            let val = tintMeterNames(row.value);
+            if (row.label === 'Meter')
+                val = val.replace(/~\d+%/, (m) => chalk.yellow(m));
+            out.push('  ' + label + val);
+        }
+        // Enjambment / end-stop — a poem-wide reading of the line-ends.
+        const enj = summariseEnjambment(stanzas);
+        if (enj)
+            out.push('  ' + chalk.bold.cyan('Enjambment:'.padEnd(w)) + chalk.dim(enj));
+        // Phonopoetics — end / caesural / head rhymes, alliteration, acrostic.
+        out.push(...renderPhonopoetics(analyzePhonopoetics(stanzas.map(st => st.lines.flatMap(l => l.results)))));
+    }
+    out.push('');
+    out.push(HR);
+    return out.join('\n');
+}