calliope-ts 0.0.2 → 0.0.3

package/dist/rhyme.js

@@ -15,6 +15,7 @@
 import * as nounsing from 'nounsing-pro';
 import { isPunctuation } from './parser.js';
 import { ictusProfile } from './scansion.js';
+import { preCaesuralWords } from './caesura.js';
 const VOWEL_RE = /^(AA|AE|AH|AO|AW|AY|EH|ER|EY|IH|IY|OW|OY|UH|UW)/;
 const PLOSIVES = new Set(['B', 'D', 'G', 'P', 'T', 'K']);
 const FRICATIVES = new Set(['V', 'DH', 'Z', 'ZH', 'JH', 'F', 'TH', 'S', 'SH', 'CH', 'HH']);
@@ -138,6 +139,8 @@ export function classifyRhymePair(a, b) {
 // Strength tiers for scheme detection.
 const STRONG = new Set(['identical', 'rich', 'perfect', 'family']);
 const SLANT = new Set(['assonant', 'consonant', 'augmented', 'diminished', 'wrenched', 'eye']);
+// Full rhyme only — the stricter bar a pre-caesural INTERNAL rhyme must clear.
+const STRICT_INTERNAL = new Set(['identical', 'rich', 'perfect']);
 /** Detect a stanza's rhyme scheme from its line-end words.  Strong rhymes
  *  bind; slant-tier rhymes bind only when no strong candidate exists. */
 export function detectScheme(endWords) {
@@ -308,10 +311,127 @@ function poemForm(stanzas) {
     }
     return undefined;
 }
+/** Syllable-bearing (non-punctuation) words of a line, in linear order. */
+function lineWords(line) {
+    return line.sentence.words.filter(w => !isPunctuation(w.lexicalClass) && w.syllables.length > 0);
+}
+/** Reader-facing surface of a word: the original case when the parser's
+ *  sentence-initial de-capitalisation touched it ("Nap"->word:"nap"), else `word`.
+ *  Rhyme CLASSIFICATION stays on `word` (it lowercases internally anyway); only
+ *  what we REPORT uses this. */
+function surfaceOf(w) {
+    return w.displayWord ?? w.word;
+}
 /** Last syllable-bearing word of a line (across its merged sentences). */
 function lineEndWord(line) {
-    const ws = line.sentence.words.filter(w => !isPunctuation(w.lexicalClass) && w.syllables.length > 0);
-    return ws.length ? ws[ws.length - 1].word : '';
+    const ws = lineWords(line);
+    return ws.length ? surfaceOf(ws[ws.length - 1]) : '';
+}
+// ─── INTERNAL (PRE-CAESURAL) RHYME — additive layer ─────────────────
+//
+// The per-stanza END-rhyme scheme (detectScheme) is the primary, UNTOUCHED
+// system: every line keeps its end letter AND its rhyme type.  Layered ON TOP,
+// a word immediately preceding a caesura that FULLY rhymes (identical/rich/
+// perfect — never the looser slant tiers, which on a caesura word are mostly
+// coincidental noise) with an end word, or with another such internal word, is
+// annotated as an INTERNAL rhyme.  It reuses the end-rhyme letter it echoes, or
+// — for an internal-only pair — a fresh letter that does not collide with the
+// stanza's end letters.  Internal rhymes render parenthesised before the end
+// letter ("(A)B"), each carrying its own type.  Purely additive: the end
+// scheme's letters and types are never modified.
+/** Attach pre-caesural internal rhymes to each line's `detail.rhyme`, on top of
+ *  the per-stanza end scheme `rhymes` (from detectScheme).  Mutates in place. */
+function attachInternalRhymes(lines, rhymes) {
+    const positions = [];
+    for (let i = 0; i < lines.length; i++) {
+        const lw = lineWords(lines[i]);
+        const endObj = lw.length ? lw[lw.length - 1] : undefined;
+        positions.push({ line: i, word: rhymes[i].endWord, kind: 'end' });
+        const pre = preCaesuralWords(lines[i].sentence.words, lines[i].phonologicalHierarchy, lines[i].phonologicalScansion.scansion);
+        for (const { word } of pre) {
+            if (word === endObj || !word.isContent)
+                continue; // the end word / function words are not internal-rhyme bearers
+            positions.push({ line: i, word: word.word, kind: 'internal' });
+        }
+    }
+    // Union-find over positions.  End-end links are NOT made (detectScheme already
+    // lettered the ends); only links INVOLVING an internal, at the full-rhyme tier.
+    const parent = positions.map((_, i) => i);
+    const find = (x) => { while (parent[x] !== x) {
+        parent[x] = parent[parent[x]];
+        x = parent[x];
+    } return x; };
+    const union = (a, b) => { const ra = find(a), rb = find(b); if (ra !== rb)
+        parent[ra] = rb; };
+    for (let a = 0; a < positions.length; a++) {
+        for (let b = a + 1; b < positions.length; b++) {
+            if (positions[a].kind === 'end' && positions[b].kind === 'end')
+                continue;
+            if (!positions[a].word || !positions[b].word)
+                continue;
+            const pair = classifyRhymePair(positions[a].word, positions[b].word);
+            if (pair && STRICT_INTERNAL.has(pair.type))
+                union(a, b);
+        }
+    }
+    // Letter per class: a class containing a lettered end takes that end's letter;
+    // an internal-only class of >=2 gets a fresh letter clear of the stanza's ends.
+    const endLetterAt = new Map();
+    positions.forEach((p, i) => { if (p.kind === 'end' && rhymes[p.line].letter !== '\u00b7')
+        endLetterAt.set(i, rhymes[p.line].letter); });
+    const used = new Set(rhymes.filter(r => r.letter !== '\u00b7').map(r => r.letter));
+    let code = 0;
+    const freshLetter = () => { let c; do {
+        c = String.fromCharCode(65 + (code++ % 26));
+    } while (used.has(c)); used.add(c); return c; };
+    const classMembers = new Map();
+    for (let i = 0; i < positions.length; i++) {
+        const r = find(i);
+        if (!classMembers.has(r))
+            classMembers.set(r, []);
+        classMembers.get(r).push(i);
+    }
+    const classLetter = new Map();
+    for (const [root, members] of classMembers) {
+        if (members.length < 2)
+            continue;
+        const endMember = members.find(m => endLetterAt.has(m));
+        if (endMember !== undefined)
+            classLetter.set(root, endLetterAt.get(endMember));
+        else if (members.some(m => positions[m].kind === 'internal'))
+            classLetter.set(root, freshLetter());
+    }
+    const typeOf = (p) => {
+        for (const m of classMembers.get(find(p)) ?? []) {
+            if (m === p)
+                continue;
+            const pair = classifyRhymePair(positions[m].word, positions[p].word);
+            if (pair && STRICT_INTERNAL.has(pair.type))
+                return pair.type;
+        }
+        return undefined;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const internal = [];
+        positions.forEach((p, idx) => {
+            if (p.line !== i || p.kind !== 'internal')
+                return;
+            const letter = classLetter.get(find(idx));
+            if (letter)
+                internal.push({ word: p.word, letter, type: typeOf(idx) });
+        });
+        const endLetter = rhymes[i].letter;
+        const intStr = internal.map(x => `(${x.letter})`).join('');
+        const notation = intStr + (endLetter !== '\u00b7' ? endLetter : (internal.length ? '' : '\u00b7'));
+        lines[i].phonologicalScansion.rhyme = {
+            endWord: rhymes[i].endWord,
+            letter: endLetter,
+            type: rhymes[i].type,
+            matchedLine: rhymes[i].matchedLine,
+            internal: internal.length ? internal : undefined,
+            notation,
+        };
+    }
 }
 /**
  * Annotate rhyme letters/types (`detail.rhyme`) and form verdicts
@@ -320,21 +440,329 @@ function lineEndWord(line) {
  * meter/scansion/certainty is touched.
  */
 export function applyRhymeAndForm(stanzas) {
+    // FORM detection uses per-stanza end-rhyme schemes (relative, restarting each
+    // stanza) — that is what couplet/quatrain/sonnet patterns are defined over.
     const analyzed = stanzas.map(lines => {
         const details = lines.map(l => l.phonologicalScansion);
         const rhymes = detectScheme(lines.map(lineEndWord));
-        return { details, rhymes };
+        return { lines, details, rhymes };
     });
     for (const { details, rhymes } of analyzed) {
         const form = stanzaForm(rhymes, details);
-        for (let i = 0; i < details.length; i++) {
-            details[i].rhyme = rhymes[i];
-            details[i].formNote = form;
-        }
+        for (const d of details)
+            d.formNote = form;
     }
     const pform = poemForm(analyzed);
     if (pform)
         for (const { details } of analyzed)
             for (const d of details)
                 d.formNote = pform;
+    // Per-stanza end-rhyme letters + TYPES (detectScheme), then the additive
+    // pre-caesural internal-rhyme layer.  Writes `detail.rhyme`; the original
+    // end-rhyme display is restored and extended, never replaced.
+    for (const { lines, rhymes } of analyzed)
+        attachInternalRhymes(lines, rhymes);
+}
+// ─── PHONOPOETICS — poem-wide end / caesural / head rhyme, alliteration,
+//     acrostic, with the maintainer's three-phase lettering ─────────────
+//
+// Lettering proceeds in three phases over ONE shared alphabet:
+//   1. END words (line 1→N): each rhyme group gets a letter A,B,C…; a later word
+//      reuses an earlier group's letter when it rhymes with it (across stanzas).
+//   2. CAESURAL words (pre-caesura): continue the alphabet (new letter per new
+//      caesural rhyme); a caesural word reuses an END letter ONLY if it rhymes
+//      with that exact end group.
+//   3. HEAD words (line-initial): continue the alphabet, a new letter per head
+//      rhyme (head rhymes do not reuse end/caesural letters).
+// Alliteration carries NO letters; an acrostic's letters are inherent.
+// Each rhyme letter is to be COLOURED by the strongest relative-stress tier among
+// the syllables it spans (`topStress`) — done at the display layer.
+const STRESS_ORDER = ['x', 'w', 'n', 'm', 's'];
+function topStressOf(...ws) {
+    let best = 'x';
+    for (const w of ws) {
+        if (!w)
+            continue;
+        for (const s of w.syllables) {
+            const r = s.relativeStress ?? 'w';
+            if (STRESS_ORDER.indexOf(r) > STRESS_ORDER.indexOf(best))
+                best = r;
+        }
+    }
+    return best;
+}
+/** First consonant phoneme of a word (for alliteration), or '' if vowel-initial/OOV. */
+function onsetPhone(word) {
+    const ph = phonesOf(word);
+    if (!ph || ph.length === 0)
+        return '';
+    const p0 = base(ph[0]);
+    return isVowelPhone(p0) ? '' : p0;
+}
+/** Whole-poem phonopoetic analysis: structured data for the Phonopoetics
+ *  synopsis section.  Read-only — never mutates the per-line scansion. */
+export function analyzePhonopoetics(stanzas) {
+    const multi = stanzas.length > 1;
+    const PLs = [];
+    stanzas.forEach((st, s) => st.forEach((line, l) => PLs.push({ line, label: multi ? `S${s + 1}L${l + 1}` : `L${l + 1}` })));
+    const endObj = (pl) => { const ws = lineWords(pl.line); return ws[ws.length - 1]; };
+    const headObj = (pl) => lineWords(pl.line).find(w => w.isContent);
+    const caesuralObjs = (pl) => {
+        const end = endObj(pl);
+        const pre = preCaesuralWords(pl.line.sentence.words, pl.line.phonologicalHierarchy, pl.line.phonologicalScansion.scansion);
+        return pre.map(p => p.word).filter(w => w !== end && w.isContent);
+    };
+    // ── Phase 1: END rhymes (poem-wide) ──
+    const endWords = PLs.map(pl => lineEndWord(pl.line));
+    const es = detectScheme(endWords);
+    const endScheme = canonicalScheme(es);
+    const byLetter = new Map();
+    es.forEach((r, i) => { if (r.letter !== '·') {
+        (byLetter.get(r.letter) ?? byLetter.set(r.letter, []).get(r.letter)).push(i);
+    } });
+    let nextCode = byLetter.size;
+    const freshLetter = () => String.fromCharCode(65 + (nextCode++ % 26));
+    const end = [];
+    for (const [letter, idxs] of byLetter) {
+        for (let k = 1; k < idxs.length; k++) {
+            const i = idxs[k], j = idxs[k - 1]; // j earlier, i later → show earlier → later
+            end.push({
+                fromWord: endWords[j], fromLabel: PLs[j].label,
+                toWord: endWords[i], toLabel: PLs[i].label,
+                letter, type: es[i].type, kind: 'end',
+                topStress: topStressOf(endObj(PLs[i]), endObj(PLs[j])),
+            });
+        }
+    }
+    const cws = [];
+    PLs.forEach((pl, i) => caesuralObjs(pl).forEach(w => cws.push({ pl: i, word: w })));
+    // (a) bind to an exact END group it rhymes with → reuse that end letter
+    for (const cw of cws) {
+        for (let i = 0; i < PLs.length; i++) {
+            if (es[i].letter === '·')
+                continue; // unrhymed end → not a "pair"
+            const ew = endObj(PLs[i]);
+            if (!ew || ew === cw.word)
+                continue;
+            const pair = classifyRhymePair(cw.word.word, ew.word);
+            if (pair && STRICT_INTERNAL.has(pair.type)) {
+                cw.letter = es[i].letter;
+                cw.pLabel = PLs[i].label;
+                cw.pWord = surfaceOf(ew);
+                cw.type = pair.type;
+                break;
+            }
+        }
+    }
+    // (b) caesural↔caesural among the still-unbound → fresh letters
+    const unbound = cws.filter(c => !c.letter);
+    for (let i = 0; i < unbound.length; i++) {
+        if (unbound[i].letter)
+            continue;
+        for (let j = 0; j < i; j++) {
+            const pair = classifyRhymePair(unbound[i].word.word, unbound[j].word.word);
+            if (pair && STRICT_INTERNAL.has(pair.type)) {
+                if (!unbound[j].letter)
+                    unbound[j].letter = freshLetter();
+                unbound[i].letter = unbound[j].letter;
+                // only the later member is annotated (points back) so each pair shows once
+                unbound[i].pLabel = PLs[unbound[j].pl].label;
+                unbound[i].pWord = surfaceOf(unbound[j].word);
+                unbound[i].type = pair.type;
+                break;
+            }
+        }
+    }
+    const caesural = cws.filter(c => c.letter && c.pLabel).map(c => ({
+        fromWord: surfaceOf(c.word), fromLabel: PLs[c.pl].label,
+        toWord: c.pWord, toLabel: c.pLabel,
+        letter: c.letter, type: c.type, kind: 'caesural',
+        topStress: topStressOf(c.word),
+    }));
+    const hws = PLs.map((pl, i) => ({ pl: i, word: headObj(pl) })).filter(h => h.word);
+    for (let i = 0; i < hws.length; i++) {
+        if (hws[i].letter)
+            continue;
+        for (let j = 0; j < i; j++) {
+            const pair = classifyRhymePair(hws[i].word.word, hws[j].word.word);
+            if (pair && STRICT_INTERNAL.has(pair.type)) {
+                if (!hws[j].letter)
+                    hws[j].letter = freshLetter();
+                hws[i].letter = hws[j].letter;
+                // only the later member is annotated (points back) so each pair shows once
+                hws[i].pLabel = PLs[hws[j].pl].label;
+                hws[i].pWord = surfaceOf(hws[j].word);
+                hws[i].type = pair.type;
+                break;
+            }
+        }
+    }
+    const head = hws.filter(h => h.letter && h.pLabel).map(h => ({
+        fromWord: surfaceOf(h.word), fromLabel: PLs[h.pl].label,
+        toWord: h.pWord, toLabel: h.pLabel,
+        letter: h.letter, type: h.type, kind: 'head',
+        topStress: topStressOf(h.word),
+    }));
+    // ── Alliteration: maximal runs (≥2) of content words sharing first letter AND
+    //    first consonant phoneme (function words may sit between, but do not count). ──
+    const alliteration = [];
+    for (const pl of PLs) {
+        const cw = lineWords(pl.line).filter(w => w.isContent);
+        let run = [];
+        const flush = () => { if (run.length >= 2)
+            alliteration.push({ label: pl.label, words: run.map(surfaceOf) }); run = []; };
+        for (const w of cw) {
+            const letter0 = (w.word.match(/[a-z]/i)?.[0] ?? '').toLowerCase();
+            const phone0 = onsetPhone(w.word);
+            if (!letter0 || !phone0) {
+                flush();
+                continue;
+            }
+            if (run.length === 0) {
+                run = [w];
+                continue;
+            }
+            const prev = run[run.length - 1];
+            const pLetter = (prev.word.match(/[a-z]/i)?.[0] ?? '').toLowerCase();
+            if (letter0 === pLetter && phone0 === onsetPhone(prev.word))
+                run.push(w);
+            else {
+                flush();
+                run = [w];
+            }
+        }
+        flush();
+    }
+    // ── Acrostic: per-stanza (and, if multi-stanza, whole-poem) first letters that
+    //    spell a dictionary word (≥3 letters). ──
+    const acrostics = [];
+    const firstLetterOf = (line) => {
+        const ws = lineWords(line);
+        return ws.length ? (ws[0].word.match(/[a-z]/i)?.[0] ?? '').toUpperCase() : '';
+    };
+    const checkAcrostic = (lines, labels) => {
+        const firsts = lines.map(firstLetterOf);
+        if (firsts.some(f => !f))
+            return;
+        const word = firsts.join('');
+        if (word.length >= 3 && phonesOf(word))
+            acrostics.push({ labels, firsts, word });
+    };
+    stanzas.forEach((st, s) => checkAcrostic(st, st.map((_, l) => multi ? `S${s + 1}L${l + 1}` : `L${l + 1}`)));
+    if (multi)
+        checkAcrostic(stanzas.flat(), PLs.map(p => p.label));
+    return { endScheme, end, caesural, head, alliteration, acrostics };
+}
+// ─── POEM-LEVEL META-MEASURE (synopsis) ─────────────────────────────
+//
+// A cumulative, NON-INTERFERING reading of the whole poem, shown at the foot of
+// the reading views.  It draws solely on determinations already made per line
+// (meter, rhythm, rhyme, form) and never overrides them.  Deliberately offers
+// SEVERAL top conclusions rather than forcing a single verdict.
+// Canonical end-rhyme schemes of the LYRICAL FORM_REGISTRY forms whose pattern is
+// expressible in plain letters (refrain forms — villanelle, pantoum, rondeau … —
+// need repetition checking and are deferred).  Used to NOTE whole-poem rhyme-
+// scheme alignment in the synopsis; the per-stanza/poem form layer remains the
+// authority for the FORM verdict itself.
+const REGISTRY_FORM_SCHEMES = [
+    { lines: 2, scheme: 'AA', name: 'Couplet' },
+    { lines: 3, scheme: 'ABA', name: 'Triplet' },
+    { lines: 4, scheme: 'ABAB', name: 'Quatrain' },
+    { lines: 5, scheme: 'AABBA', name: 'Limerick' },
+    { lines: 6, scheme: 'ABABCC', name: 'Sextilla' },
+    { lines: 7, scheme: 'ABABBCC', name: 'Septet (rhyme royal)' },
+    { lines: 9, scheme: 'AAABBBCCC', name: 'Triad' },
+    { lines: 10, scheme: 'ABABCDECDE', name: 'English Ode' },
+    { lines: 14, scheme: 'ABABCDCDEFEFGG', name: 'Shakespearean Sonnet' },
+    { lines: 14, scheme: 'ABBAABBACDCDCD', name: 'Petrarchan Sonnet' },
+    { lines: 14, scheme: 'ABBAABBACDECDE', name: 'Petrarchan Sonnet' },
+];
+function matchRegistryForm(totalLines, canonicalEndScheme) {
+    return REGISTRY_FORM_SCHEMES.find(f => f.lines === totalLines && f.scheme === canonicalEndScheme)?.name;
+}
+const descriptorOf = (d) => d.metricalityNote ? 'plausible prose'
+    : d.rhythmNote ? d.rhythmNote // accentual/dolnik/taktovik → beats
+        : d.meterName === 'free verse' ? 'free verse'
+            : d.meter; // e.g. "iambic pentameter"
+// Compact metre labels for the synopsis ("iambic pentameter" → "iamb penta").
+// Rhythm notes ("4/3 ♪beat accentual"), "free verse", and "plausible prose" are
+// left untouched (they are not family+foot labels).
+const _FAMILY_ABBR = {
+    iambic: 'iamb', trochaic: 'troch', dactylic: 'dact', anapestic: 'anap',
+    amphibrachic: 'amph', bacchic: 'bacch', spondaic: 'spon', pyrrhic: 'pyrr',
+};
+const _FOOT_ABBR = {
+    monometer: 'mono', dimeter: 'di', trimeter: 'tri', tetrameter: 'tetra',
+    pentameter: 'penta', hexameter: 'hexa', heptameter: 'hepta', octameter: 'octa',
+};
+function abbrevMeter(label) {
+    const parts = label.split(' ');
+    if (parts.length === 2 && _FAMILY_ABBR[parts[0]] && _FOOT_ABBR[parts[1]]) {
+        return `${_FAMILY_ABBR[parts[0]]} ${_FOOT_ABBR[parts[1]]}`;
+    }
+    return label;
+}
+/**
+ * Build the cumulative poem synopsis: top meter(s)/mixed meters (accentual forms
+ * reported in beats), the poem-wide rhyme scheme (with internal rhymes), and the
+ * poetic-form alignment.  Reads only existing per-line determinations.
+ */
+export function summarizePoem(stanzas) {
+    const lines = stanzas.flat();
+    const details = lines.map(l => l.phonologicalScansion);
+    const N = details.length;
+    const rows = [];
+    if (N === 0)
+        return rows;
+    // ── Meter — several top conclusions, never forced into one ──
+    const tally = new Map();
+    for (const d of details)
+        tally.set(descriptorOf(d), (tally.get(descriptorOf(d)) ?? 0) + 1);
+    const ranked = [...tally.entries()].sort((a, b) => b[1] - a[1]);
+    let meterVal;
+    if (N === 1) {
+        meterVal = abbrevMeter(ranked[0][0]);
+    }
+    else if (ranked[0][1] / N >= 0.6) {
+        const rest = ranked.slice(1, 3).map(([m, c]) => `${abbrevMeter(m)} (${c})`);
+        meterVal = `predominantly ${abbrevMeter(ranked[0][0])} (${ranked[0][1]}/${N})`
+            + (rest.length ? `; also ${rest.join(', ')}` : '');
+    }
+    else {
+        meterVal = 'Mixed | ' + ranked.slice(0, 3).map(([m, c]) => `${abbrevMeter(m)} (${c}/${N})`).join(' · ');
+    }
+    // "Rhythm" = the metre make-up; "Meter" = the mean fit % (the maintainer's
+    // synopsis taxonomy).
+    rows.push({ label: 'Rhythm', value: meterVal });
+    // ── Meter — mean of the per-line fit certainties ──
+    const meanCert = Math.round(details.reduce((s, d) => s + d.certainty, 0) / N);
+    rows.push({ label: 'Meter', value: `~${meanCert}% mean line-wise fit` });
+    // ── Form — the form layer's verdict(s) + registry-scheme alignment.  (The
+    // detailed rhyme listing now lives in the Phonopoetics section; the synopsis
+    // carries only the canonical End-Rhyme Scheme, below.) ──
+    const endRhymes = N >= 2 ? detectScheme(lines.map(lineEndWord)) : [];
+    const endScheme = endRhymes.length ? canonicalScheme(endRhymes) : '';
+    const hasEndRhyme = endRhymes.some(r => r.letter !== '·');
+    const forms = [...new Set(details.map(d => d.formNote).filter((x) => !!x))];
+    let formVal = forms.length ? forms.join(' · ') : undefined;
+    if (N >= 2) {
+        const reg = matchRegistryForm(N, endScheme);
+        if (reg && !(formVal && formVal.includes(reg))) {
+            formVal = (formVal ? formVal + ' · ' : '') + `aligns with the ${reg} scheme`;
+        }
+    }
+    if (formVal)
+        rows.push({ label: 'Form', value: formVal });
+    // ── End-Rhyme Scheme — poem-wide canonical scheme, its own row (only end
+    // rhymes are matched against forms; caesural/head live in Phonopoetics). ──
+    if (hasEndRhyme)
+        rows.push({ label: 'End-Rhyme Scheme', value: endScheme });
+    // ── Heterometric advisory — the whole-poem observation that per-line beat
+    // counts vary widely (kept OUT of the per-line display, as an advisory here). ──
+    const beats = details.map(d => (d.footCount > 0 ? d.footCount : ictusProfile(d.scansion).ictuses));
+    const lo = Math.min(...beats), hi = Math.max(...beats);
+    if (N >= 3 && hi - lo >= 3) {
+        rows.push({ label: 'Note', value: `line lengths vary — ${lo}–${hi} beats per line` });
+    }
+    return rows;
 }

package/dist/scansion.d.ts

@@ -1,5 +1,14 @@
 import { ClsWord, IntonationalUnit, KeyStress, MetreName, PhonologicalScansionDetail } from './types.js';
 export declare function extractKeyStresses(ius: IntonationalUnit[], words: ClsWord[]): KeyStress[];
+/**
+ * If a line reads as plausible prose (see above), return the advisory hedge
+ * string; otherwise undefined.  Reads only fields already present on the detail,
+ * so it runs as a late, non-destructive pipeline pass (`applyMetricalityLayer`).
+ */
+export declare function metricalityVerdict(detail: PhonologicalScansionDetail): string | undefined;
+/** Set `detail.metricalityNote` on every line that reads as plausible prose.
+ *  Non-destructive: only the new advisory field is written. */
+export declare function applyMetricalityLayer(details: PhonologicalScansionDetail[]): void;
 export declare function scoreMeters(keyStresses: KeyStress[], words: ClsWord[], ius?: IntonationalUnit[], force?: MetreName): PhonologicalScansionDetail;
 /** Per-line ictus profile parsed from a scansion string ("ns|wx|ns|ws|ws"). */
 export interface IctusProfile {

package/dist/scansion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scansion.d.ts","sourceRoot":"","sources":["../src/scansion.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,OAAO,EACP,gBAAgB,EAGhB,SAAS,EACT,SAAS,EAET,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAgLpB,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAwCzF;AA2ZD,wBAAgB,WAAW,CACzB,WAAW,EAAE,SAAS,EAAE,EACxB,KAAK,EAAE,OAAO,EAAE,EAChB,GAAG,CAAC,EAAE,gBAAgB,EAAE,EACxB,KAAK,CAAC,EAAE,SAAS,GAChB,0BAA0B,CA4I5B;AAmBD,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CA8B3D;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,EAAE,GAAG,IAAI,CAmF5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,0BAA0B,EAAE,EACrC,GAAG,GAAE,MAAc,GAClB,IAAI,CA6DN"}
+{"version":3,"file":"scansion.d.ts","sourceRoot":"","sources":["../src/scansion.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,OAAO,EACP,gBAAgB,EAGhB,SAAS,EACT,SAAS,EAET,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAgLpB,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAwCzF;AA8cD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,GAAG,SAAS,CAYzF;AAED;+DAC+D;AAC/D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,0BAA0B,EAAE,GAAG,IAAI,CAEjF;AAED,wBAAgB,WAAW,CACzB,WAAW,EAAE,SAAS,EAAE,EACxB,KAAK,EAAE,OAAO,EAAE,EAChB,GAAG,CAAC,EAAE,gBAAgB,EAAE,EACxB,KAAK,CAAC,EAAE,SAAS,GAChB,0BAA0B,CA4I5B;AAmBD,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CA8B3D;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,EAAE,GAAG,IAAI,CA0F5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,0BAA0B,EAAE,EACrC,GAAG,GAAE,MAAc,GAClB,IAAI,CAmGN"}