calliope-ts 0.0.1

package/src/display.ts

@@ -0,0 +1,954 @@
+// display.ts — Unified, integrated CLI display for Calliope TS
+// Shows ALL information layers in a single comprehensive view
+
+import chalk from 'chalk';
+import {
+  ClsWord,
+  ClsSentence,
+  IntonationalUnit,
+  PhonologicalPhrase,
+  CliticGroup,
+  StressLevel,
+  LineResult,
+  SyllableDisplayEntry,
+  MeterScore,
+} from './types.js';
+import { isPunctuation } from './parser.js';
+import { syllabifyWord, syllableVowelLengths } from './phonological.js';
+
+// ═══════════════════════════════════════════════════════════════════════
+// COLOUR SYSTEM — Conceptually motivated palettes
+// ═══════════════════════════════════════════════════════════════════════
+
+// Lexical stress (numeric 0–3): blue→magenta→red→bold red
+// Represents phonetic prominence from dictionary
+const LEX0 = (s: string) => chalk.blue(s);
+const LEX1 = (s: string) => chalk.magenta(s);
+const LEX2 = (s: string) => chalk.red(s);
+const LEX3 = (s: string) => chalk.red.bold(s);
+
+function lexColour(val: number): (s: string) => string {
+  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: string) => chalk.hex('#b0b0b0')(s);
+const REL_W = (s: string) => chalk.cyan(s);
+const REL_N = (s: string) => chalk.green(s);
+const REL_M = (s: string) => chalk.yellow(s);
+const REL_S = (s: string) => chalk.redBright(s);
+
+function relColour(rel: StressLevel): (s: string) => string {
+  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);
+
+// ═══════════════════════════════════════════════════════════════════════
+// PER-SYLLABLE DATA STRUCTURE
+// ═══════════════════════════════════════════════════════════════════════
+
+interface ColSyl {
+  chunk: string;
+  word: string;
+  pos: string;
+  isContent: boolean;
+  lexStress: number;
+  relStress: StressLevel;
+  cpId: number;
+  ppId: number;
+  iuId: number;
+  isFirstInWord: boolean;
+  isFirstInCP: boolean;
+  isFirstInPP: boolean;
+  isFirstInIU: boolean;
+  isLastInCP: boolean;
+  isLastInPP: boolean;
+  isLastInIU: boolean;
+  depLabel: string;
+  govWord: string;
+  globalIdx: number;
+  wordRef: ClsWord;
+}
+
+function buildColSyls(words: ClsWord[], ius: IntonationalUnit[]): ColSyl[] {
+  const result: ColSyl[] = [];
+  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: LineResult, rawLine?: string): string {
+  const words = result.sentence.words;
+  const ius = result.phonologicalHierarchy;
+  const detail = result.phonologicalScansion;
+  const colSyls = buildColSyls(words, ius);
+
+  const lines: string[] = [];
+  lines.push('');
+  lines.push(HR);
+
+  // ── Layer 1: Original text with word-role coloring ──────────────
+  lines.push(H1('Original Text'));
+  lines.push('');
+  const textParts: string[] = [];
+  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<ClsWord>();
+  const dedupedEntries: { col: ColSyl; word: ClsWord }[] = [];
+  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: string[] = [];
+  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 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: string[] = [];
+  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: string[] = [];
+  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('|');
+
+  interface LinearSyl {
+    chunk: string;
+    relStress: StressLevel;
+    wordRef: ClsWord;
+  }
+  const linearSyls: LinearSyl[] = [];
+  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: string): boolean {
+    return 'xXwWnNmMsS'.includes(ch);
+  }
+
+  let sylIdx = 0;
+  const footDisplays: string[] = [];
+  let prevWordRef: ClsWord | null = 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: string[] = [];
+  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(): string {
+  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');
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// GLOSSARIES — Penn POS tags & grammatical dependencies
+// (For the long-form Display Legend [menu] and the per-line mini-legend in the
+//  detailed views.  NOT shown in the compact in-output legend above.)
+// ═══════════════════════════════════════════════════════════════════════
+
+interface Gloss { name: string; eg: string; }
+
+// 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: string; tags: [string, Gloss][] }[] = [
+  { 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: string; deps: [string, Gloss][] }[] = [
+  { 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: Record<string, Gloss> = Object.fromEntries(POS_GROUPS.flatMap(g => g.tags));
+const DEP_GLOSS: Record<string, 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: string, g: Gloss, tagWidth: number): string {
+  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(): string {
+  const out: string[] = [];
+  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: ClsWord[]): string[] {
+  const posSeen: string[] = [];
+  const depSeen: string[] = [];
+  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: string): string => name.split(/,| \(/)[0].trim();
+  const out: string[] = [];
+  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;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// READING VIEW — original formatting, stress-gradient coloured per syllable
+// ═══════════════════════════════════════════════════════════════════════
+
+/** One input line with its (1+) parsed sentence results. */
+export interface ReadingLine {
+  raw: string;            // the original line text, verbatim
+  results: LineResult[];  // a line may parse into more than one sentence
+}
+
+/** A stanza: a run of consecutive non-blank input lines. */
+export interface ReadingStanza {
+  lines: ReadingLine[];
+}
+
+/** Surface form reduced to bare lowercase letters (drops apostrophes/hyphens). */
+function normWordForm(s: string): string {
+  return s.toLowerCase().replace(/[^a-z]/g, '');
+}
+
+/** Colour each orthographic syllable of an original token by its relative stress. */
+function colourToken(tokenText: string, word: ClsWord): string {
+  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: string, words: ClsWord[]): string {
+  const tokenRe = /[A-Za-z]+(?:['’\-][A-Za-z]+)*/g;
+  let out = '';
+  let cursor = 0;
+  let wi = 0;
+  let m: RegExpExecArray | null;
+  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: ClsWord | undefined): boolean => {
+      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 PLACEMENT
+// ═══════════════════════════════════════════════════════════════════════
+
+type CaesuraKind = 'hard' | 'soft';
+
+/** Foot-boundary syllable indices from a scansion string (cumulative syllable
+ *  count after each foot; silent beats '-' are not syllables). */
+function footBoundarySet(scansion: string): Set<number> {
+  const set = new Set<number>();
+  let c = 0;
+  for (const foot of scansion.split('|')) {
+    for (const ch of foot) if ('xwnms'.includes(ch)) c++;
+    set.add(c);
+  }
+  return set;
+}
+
+// A new phonological/syntactic phrase opens at these POS tags: prepositions &
+// subordinators (IN), infinitival "to" (TO), coordinators (CC), wh/relativizers,
+// verb-particles (RP), and the predicate's verb/modal.  The major medial caesura
+// of a line falls immediately BEFORE such a word — far more reliably read off the
+// (robust) POS tags than off FinNLP's (noisy) phonological-phrase grouping, which
+// mis-bracketed e.g. "The epic | feast…".  Determiners/articles are excluded (they
+// continue a phrase a preposition already opened: "as | one empty bag").
+const PHRASE_ONSET_POS = new Set([
+  'IN', 'TO', 'CC', 'WDT', 'WP', 'WP$', 'WRB', 'RP',
+  'VB', 'VBD', 'VBG', 'VBN', 'VBP', 'VBZ', 'MD',
+]);
+
+// Directional/spatial adverbs that open a phrase ("snowed-in OUT of many routes",
+// "drifting DOWN to sleep").  FinNLP often tags these RB rather than RP/IN, so the
+// POS set alone misses them; a small curated lemma list recovers them with low
+// over-fire risk (a generic RB like "very"/"quickly" is NOT a phrase onset).
+const DIRECTIONAL_ONSET = new Set([
+  'out', 'in', 'up', 'down', 'off', 'away', 'back', 'forth', 'over',
+  'around', 'along', 'through', 'apart', 'aside', 'onward', 'onwards',
+]);
+
+/** True if a word opens a new phonological/syntactic phrase (a caesura candidate). */
+function isPhraseOnset(w: ClsWord): boolean {
+  if (PHRASE_ONSET_POS.has(w.lexicalClass)) return true;
+  return w.lexicalClass === 'RB' && DIRECTIONAL_ONSET.has(w.word.toLowerCase());
+}
+
+/**
+ * Caesura positions for a line, keyed by the syllable index AFTER which the pause
+ * falls (= number of syllables to its left).
+ *  • 'hard' — an overt break at an Intonational-Unit boundary (comma, dash, colon,
+ *    semicolon …): the punctuation projection.
+ *  • 'soft' — a single INFERRED medial caesura for a punctuation-free line (Kiparsky
+ *    1975, via McAleese: "phonological phrasing determines the location of caesurae
+ *    in verse").  Candidates are the boundaries just before a phrase/clause onset
+ *    (PHRASE_ONSET_POS); the one nearest the line's midpoint that lies in the
+ *    central third AND coincides with a foot boundary wins — so it is medial, never
+ *    mid-foot, and consistent across structurally-parallel lines.  Read in LINEAR
+ *    order (robust to clitic-group reordering); needs a line of ≥ 8 syllables.
+ */
+function computeCaesurae(words: ClsWord[], ius: IntonationalUnit[], scansion?: string): Map<number, CaesuraKind> {
+  const caes = new Map<number, CaesuraKind>();
+  const iuOf = new Map<ClsWord, number>();
+  for (let i = 0; i < ius.length; i++) {
+    for (const pp of ius[i].phonologicalPhrases) {
+      for (const cg of pp.cliticGroups) for (const tok of cg.tokens) iuOf.set(tok, i);
+    }
+  }
+  let cum = 0;
+  let prevIu: number | undefined;
+  let prevWasContentful = false;
+  const onsetPositions: number[] = [];
+  for (const w of words) {
+    if (isPunctuation(w.lexicalClass) || w.syllables.length === 0) continue;
+    const iu = iuOf.get(w);
+    if (prevIu !== undefined && iu !== undefined && iu !== prevIu) {
+      caes.set(cum, 'hard');                            // IU boundary → hard caesura
+    }
+    // A phrase-onset word that is NOT the line's first word opens a candidate
+    // caesura immediately before it.
+    if (prevWasContentful && isPhraseOnset(w)) onsetPositions.push(cum);
+    cum += w.syllables.length;
+    prevIu = iu;
+    prevWasContentful = true;
+  }
+  const total = cum;
+
+  // Infer ONE medial caesura only when the line carries no overt (hard) break.
+  if (caes.size === 0 && total >= 8 && onsetPositions.length > 0) {
+    const footEdges = scansion ? footBoundarySet(scansion) : null;
+    const mid = total / 2;
+    const lo = Math.max(2, Math.ceil(total / 3));
+    const hi = Math.floor((2 * total) / 3);
+    let best = -1, bestDist = Infinity;
+    for (const c of onsetPositions) {
+      if (c < lo || c > hi) continue;                   // medial third only
+      if (footEdges && !footEdges.has(c)) continue;     // align to a foot boundary
+      const d = Math.abs(c - mid);
+      if (d < bestDist) { bestDist = d; best = c; }
+    }
+    if (best > 0) caes.set(best, 'soft');
+  }
+  return caes;
+}
+
+/** Render the glyph for a caesura kind. */
+function caesuraGlyph(kind: CaesuraKind): string {
+  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: string, caesurae?: Map<number, CaesuraKind>): string {
+  let out = '';
+  let sc = 0;                       // syllables emitted so far
+  const emitted = new Set<number>();
+  const caesAt = (): string => {
+    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 as StressLevel)(ch);
+      sc++;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+const METER_ABBR: Record<string, string> = {
+  iambic: 'iamb', trochaic: 'troch', anapestic: 'anap', dactylic: 'dact',
+  amphibrachic: 'amph', bacchic: 'bacch', spondaic: 'spon', pyrrhic: 'pyrr',
+  'free verse': 'free',
+};
+
+/** Compact top-3 meter fit scores, e.g. "(anap 0.81 · iamb 0.77 · amph 0.74)". */
+function formatRanking(ranking?: MeterScore[]): string {
+  if (!ranking || ranking.length === 0) return '';
+  const top = ranking.slice(0, 3)
+    .map(r => `${METER_ABBR[r.meter] ?? r.meter} ${r.score.toFixed(2)}`);
+  return chalk.dim('(' + top.join(' · ') + ')');
+}
+
+/** 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: { consensusMeter?: string; standaloneMeter?: string }): string {
+  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 /
+ *  alternating ictus counts), set by the rhythm layer.  Empty when the line
+ *  has no such reading. */
+function rhythmNoteStr(detail: { rhythmNote?: string }): string {
+  if (!detail.rhythmNote) return '';
+  return chalk.magenta.dim(`  ♪ ${detail.rhythmNote}`);
+}
+
+/** End-rhyme chip for a line: scheme letter plus (dimmed) rhyme type when the
+ *  line rhymes with an earlier one — e.g. "B(perfect)"; '·' = unrhymed. */
+function rhymeStr(detail: { rhyme?: { letter: string; type?: string } }): string {
+  if (!detail.rhyme) return '';
+  const { letter, type } = detail.rhyme;
+  if (letter === '·') return '  ' + chalk.dim('·');
+  return '  ' + chalk.yellowBright(letter) + (type ? chalk.dim(`(${type})`) : '');
+}
+
+/** Non-punctuation, syllable-bearing words across all of a line's sentences. */
+function collectLineWords(ln: ReadingLine): ClsWord[] {
+  const ws: ClsWord[] = [];
+  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;
+}
+
+/**
+ * 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.
+ */
+export function renderReadingView(stanzas: ReadingStanza[]): string {
+  const out: string[] = [];
+  const multiStanza = stanzas.length > 1;
+
+  out.push('');
+  out.push(HR);
+  out.push(H1('Reading View') + chalk.dim('  — stress gradient over the original text'));
+  out.push('');
+
+  // ── Block 1: the poem, original formatting, syllables coloured ──
+  for (let s = 0; s < stanzas.length; s++) {
+    for (const ln of stanzas[s].lines) {
+      out.push(projectStressOntoLine(ln.raw, collectLineWords(ln)));
+    }
+    if (s < stanzas.length - 1) out.push('');
+  }
+
+  out.push('');
+  out.push(HR_THIN);
+  out.push(H1('Stress Maps & Meter') + 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 + '   ' +
+          chalk.whiteBright(d.meter) + (rank ? '   ' + rank : '') + consensusNote(d) + rhythmNoteStr(d) + rhymeStr(d));
+      }
+    }
+    if (multiStanza && s < stanzas.length - 1) out.push('');
+  }
+
+  out.push('');
+  out.push(HR_THIN);
+  out.push(renderLegend());
+  out.push(HR);
+  return out.join('\n');
+}