calliope-ts 0.0.1

package/README.md

@@ -0,0 +1,485 @@
+# Calliope TS
+
+**Calliope TS** is a phonological poetry-scansion toolkit for TypeScript / Node.js.
+Give it a poem (or a single line of verse) and it will tell you — and *show*
+you — how the poem sounds: which syllables carry stress and how much, where the
+metrical beats fall, what meter each line is written in, how certain that
+reading is, what the rhyme scheme is, and what poetic form the stanzas add up
+to.
+
+It is not a syllable-counter with a rulebook bolted on. Calliope TS scans verse
+the way a trained reader does: it first works out how the words would actually
+be *spoken* — dictionary stress, phrase rhythm, sentence intonation — and only
+then asks which metrical pattern that spoken contour fits best.
+
+```
+$ calliope-ts --reading exile.txt
+
+Reading View  — stress gradient over the original text
+
+He happens to be a French poet, that thin,        ← every syllable colour-coded
+book-carrying man with a bristly gray chin;          by its stress level
+...
+
+Stress Maps & Meter  — top-3 fit scores per line
+  S1L1   nsw|xwx|msw ‖ xs    amphibrachic tetrameter  (amph 1.20 · iamb 1.14 ·
+         anap 1.13)  A
+  S1L2   m|-mww|sxx|mwm|s    amphibrachic tetrameter  ≈ continuity; standalone:
+         dactylic tetrameter  A(perfect)
+  ...
+```
+
+---
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start (CLI)](#quick-start-cli)
+- [Reading the output](#reading-the-output)
+- [How it works: the scansion pipeline](#how-it-works-the-scansion-pipeline)
+- [Programmatic usage (API)](#programmatic-usage-api)
+- [Examples](#examples)
+- [Background and lineage](#background-and-lineage)
+- [Scope, strengths, and honest limitations](#scope-strengths-and-honest-limitations)
+- [Development](#development)
+- [License and credits](#license-and-credits)
+
+---
+
+## Installation
+
+Requires **Node.js ≥ 20** (≥ 22 recommended — one optional analysis stage, the
+dependency-tree repair, needs Node's `require(esm)` support and degrades
+gracefully without it).
+
+```bash
+# As a global CLI tool
+npm install -g calliope-ts
+
+# Or as a library in your project
+npm install calliope-ts
+```
+
+From a clone of the repository:
+
+```bash
+npm install
+npm run build      # compiles src/ → dist/
+npm test           # vitest suite
+```
+
+---
+
+## Quick start (CLI)
+
+```bash
+# 1. Scan a line directly
+calliope-ts "Shall I compare thee to a summer's day?"
+
+# 2. Scan a whole poem from a file (blank lines separate stanzas)
+calliope-ts poem.txt
+
+# 3. The Reading View — the poem itself, colour-coded by stress (recommended
+#    for whole poems; add -r or --reading)
+calliope-ts --reading poem.txt
+
+# 4. Pipe text in
+cat poem.txt | calliope-ts --reading
+
+# 5. Interactive menu (run with no arguments in a terminal)
+calliope-ts
+```
+
+The interactive menu offers: multi-line paste-and-scan (reading view),
+single-line detailed analysis, line-by-line analysis, file input in either
+view, and a **legend** explaining every symbol and colour.
+
+There are two display modes:
+
+| Mode | Flag | What you get |
+|---|---|---|
+| **Detailed view** | *(default)* | Per line: the tagged text, the phrase structure, lexical and relative stress maps, phonological bracketing, the foot-by-foot scansion, the dependency tree, and a summary (meter, fit %, scansion string). |
+| **Reading view** | `--reading` / `-r` | The poem in its original formatting with every syllable coloured by stress, followed by one compact line per verse-line: stress map, meter, top-3 candidate scores, rhyme-scheme letter, and any rhythm/continuity notes. |
+
+---
+
+## Reading the output
+
+### The five stress levels
+
+Calliope TS grades every syllable on a five-tier *relative* scale (this is the
+core representation everything else is built on):
+
+| Symbol | Name | Typical bearer |
+|---|---|---|
+| `x` | zero-provision | maximally reduced function words: *the, a, of, and, to* |
+| `w` | weak | unstressed syllables of content words; unreduced function words (*be, just, here*) |
+| `n` | low | lightly stressed syllables; pronouns and modals with citation stress (*he, might*) |
+| `m` | moderate | secondary stresses; stressed syllables demoted by a neighbouring stronger one |
+| `s` | strong | primary stresses, phrase peaks, line-final nuclei |
+
+A line's **stress map** is simply its syllables in order, e.g.
+`xs|wxm|wxs|xws` — with `|` marking foot boundaries, `‖` a strong caesura
+(major punctuation pause), `¦` a lighter phrase break, and `-` a "silent beat"
+inside a stress clash.
+
+### Meter lines
+
+```
+S1L2   m|-mww|sxx|mwm|s   amphibrachic tetrameter   (dact 1.21 · amph 1.17 ·
+       anap 1.16)  ≈ continuity; standalone: dactylic tetrameter  A(perfect)
+```
+
+- **`amphibrachic tetrameter`** — the line's meter: foot type + number of feet.
+- **`(dact 1.21 · amph 1.17 · anap 1.16)`** — the top three candidate meters
+  with their raw fit scores. The named meter need not be the numerically
+  first candidate: ties between sibling meters are resolved by principled
+  criteria (word integrity, caesura alignment, stanza context — see below).
+- **`≈ continuity; standalone: dactylic tetrameter`** — this line, taken
+  alone, fits dactylic a hair better; but the stanza is amphibrachic and the
+  line fits amphibrachic nearly as well, so the continuity reading is
+  promoted to the base reading and the standalone result is kept as a note.
+- **`↔ aligns w/ stanza …`** — a weaker version of the same: the line stays
+  with its own meter but is flagged as compatible with the stanza's.
+- **`♪ 4-beat accentual`** / `♪ 3-ictus dolnik` — a *rhythm note*: the stanza
+  is not accentual-syllabic at all but keeps a constant count of strong beats
+  with varying syllable counts (see "Beyond classical meters" below).
+- **`A`, `B(perfect)`, `·`** — the rhyme-scheme letter for the line's end
+  word, with the rhyme type when the line rhymes with an earlier one
+  (`perfect`, `rich`, `family`, `assonant`, `consonant`, `augmented`,
+  `diminished`, `wrenched`, `eye`, `identical`). `·` = unrhymed.
+- **`❡ ballad stanza (ABCB, 4·3)`** — a stanza-level *form* verdict (shown in
+  the stanza header): ballad stanza, blank verse, couplet, limerick,
+  Shakespearean/Petrarchan sonnet, terza rima, etc.
+- **Certainty / fit %** (detailed view) — the share of the line realised by
+  clean, unsubstituted feet, tempered by phrase-edge agreement. A perfectly
+  regular line reads 100%; real verse usually lands between 50 and 90.
+
+---
+
+## How it works: the scansion pipeline
+
+Most automatic scanners pattern-match syllable counts against meter templates.
+Calliope TS instead follows the **phonological scansion** method: derive the
+line's natural spoken prominence first, then fit meters to it. The pipeline
+has eight stages.
+
+**1. Parsing (who does what in the sentence).**
+The line is tokenized, part-of-speech tagged, and dependency-parsed (which
+word grammatically governs which) using the FinNLP family of libraries
+(`lexed`, `en-pos`, `en-parse`). Two correction layers sit inside this stage,
+because verse breaks taggers in predictable ways: a *tag-repair* pass fixes
+systematic errors before the dependency tree is built (archaic forms like
+*thou/thy/doth/wherefore*, the pronoun *I*, perfect-tense participles like
+*had quit*), and a *tree-repair* pass (built on the
+[depedits](https://www.npmjs.com/package/depedits) rule engine) fixes
+systematic attachment errors after it (e.g. noun compounds parsed as double
+objects). Hyphenated compounds and contractions (*we'll*, *don't*, archaic
+*fix'd*) are re-merged into single metrical words.
+
+**2. Lexical stress (how each word is pronounced).**
+Every word is looked up in an augmented CMU pronouncing dictionary
+([nounsing-pro](https://www.npmjs.com/package/nounsing-pro)): syllable count,
+stress pattern (primary / secondary / unstressed), syllable weights, and
+vowel quantities. Words not in the dictionary go through a morphological
+fallback (strip a productive suffix, look up the stem, restore) and finally a
+quantity-sensitive English Stress Rule. Poetic elisions are honoured:
+*heav'n* is one syllable, *o'er* one, *th'expense* two, *'tis/'twas* reduce,
+and archaic *-'d* / *-'st* forms (*fix'd*, *stopp'st*) keep their elided
+syllable counts.
+
+**3. The prosodic hierarchy (how the line phrases).**
+Words are grouped the way speech groups them: each content word attracts its
+function-word satellites into a **clitic group** (CP); clitic groups join into
+**phonological phrases** (PP) along the syntactic dependencies; phrases join
+into **intonational units** (IU) bounded by major punctuation. Crucially, the
+**line is the scansion domain**: a verse line containing several grammatical
+sentences is still ONE metrical unit (the internal full stops become strong
+caesurae), and quotation marks are *not* treated as prosodic breaks.
+
+**4. Phrase-level stress rules.**
+Three classic rules adjust the dictionary stresses in context: the **compound
+rule** (left element stressed: *CITY hall*), the **nuclear stress rule** (the
+last content word of an intonational unit gets the phrase's peak), and a set
+of **clash resolutions** (two adjacent strong syllables cannot both keep full
+prominence — one yields, chosen by syntactic direction). The result is mapped
+onto the five-tier `x w n m s` scale.
+
+**5. Key stresses, "beginnings free, endings strict."**
+Following McAleese's central insight, the stresses at the *right edges* of
+prosodic units are the reliable ones — speakers may start a phrase loosely
+but they land its ending. Each unit contributes its right-edge "key stress"
+with a weight (intonational unit > phrase > long word > clitic group), and
+meters that place beats on those key stresses are rewarded.
+
+**6. Meter fitting (dynamic programming).**
+For each of seven candidate meters — iambic, trochaic, anapestic, dactylic,
+**amphibrachic**, bacchic, spondaic — the engine finds the optimal division of
+the line into feet, using that meter's full inventory of legitimate
+variations: inversions at line-start or after a caesura, pyrrhic and spondaic
+substitutions, catalexis (truncated final foot), anacrusis (extrametrical
+upbeat), feminine endings, acephalous openings. Each syllable is scored
+against the metrical position it lands in (a strong syllable in a beat slot
+is ideal; a reduced clitic forced onto a beat is the cardinal violation), and
+an **Attridge promotion** rule lets a weak syllable carry a beat when it is
+flanked by even weaker ones (*"happens to BE a French poet"*) — which is how
+real readers actually deliver such lines.
+
+**7. Arbitration and context.**
+The winning meter is not just the top raw score:
+- **Ternary siblings** (anapest / amphibrach / dactyl) frequently fit a line
+  with the *identical* beat pattern — then the name is decided by which
+  division avoids splitting words across feet and aligns with the line's
+  pauses, not by score noise.
+- **Stanza consensus**: each stanza's dominant meter is identified (for
+  ternary verse, by the stanza's *anacrusis profile* — how many slack
+  syllables open the lines, following Russian metrics). A line that fits the
+  dominant meter nearly as well as its own standalone winner **adopts the
+  dominant meter** as its base reading, with the standalone reading preserved
+  as a note. Metrical continuity outranks a hair of fit score, exactly as it
+  does for a human scander.
+
+**8. Beyond classical meters.**
+If a stanza's syllable counts vary while its strong-beat counts stay constant
+— and no classical meter dominates — the stanza is read as **accentual verse**
+(`4-beat accentual`), or more precisely as a **dolnik** (1–2 slack syllables
+between beats) or **taktovik** (1–3), the categories of Russian verse theory
+that also fit much English song, ballad, and modernist verse. Free verse is
+recognised both line-by-line and stanza-wide. Independently, a **rhyme
+layer** classifies every line-end pair (perfect / rich / family / slant /
+eye / … rhymes, masculine / feminine / dactylic), detects the rhyme scheme,
+and a **form layer** names what the stanzas amount to: ballad stanza (rhyme
+scheme *and* alternating 4·3 beats), blank verse (unrhymed iambic
+pentameter), couplets, quatrains, limerick, rhyme royal, Shakespearean or
+Petrarchan sonnet, terza rima.
+
+---
+
+## Programmatic usage (API)
+
+```ts
+import {
+  analyzeStanzas,          // poem text → LineResult[][]  (per stanza, per line)
+  analyzeText,             // poem text → LineResult[]    (flat)
+  analyzeReadingDocument,  // poem text → ReadingStanza[] (keeps verbatim lines)
+} from 'calliope-ts';
+```
+
+### Scan a poem
+
+```ts
+import { analyzeStanzas } from 'calliope-ts';
+
+const poem = `He happens to be a French poet, that thin,
+book-carrying man with a bristly gray chin;
+you meet him whenever you go`;
+
+const stanzas = analyzeStanzas(poem);
+
+for (const stanza of stanzas) {
+  for (const line of stanza) {
+    const d = line.phonologicalScansion;
+    console.log(d.meter);          // "amphibrachic tetrameter"
+    console.log(d.scansion);       // "nsw|xwx|msw|xs"
+    console.log(d.footCount);      // 4
+    console.log(d.certainty);      // 0–100
+    console.log(d.ranking);        // [{ meter: 'amphibrachic', score: 1.20 }, …]
+    console.log(d.standaloneMeter);// set when stanza continuity renamed the line
+    console.log(d.rhythmNote);     // "4-beat accentual", "3-ictus dolnik", …
+    console.log(d.rhyme);          // { endWord, letter: 'A', type: 'perfect', … }
+    console.log(d.formNote);       // "ballad stanza (ABCB, 4·3)", "blank verse", …
+  }
+}
+```
+
+### Inspect the linguistic analysis
+
+Each `LineResult` also carries the full intermediate analysis:
+
+```ts
+const line = stanzas[0][0];
+
+// Words with POS tags, content/function status, and per-syllable stress
+for (const w of line.sentence.words) {
+  console.log(w.word, w.lexicalClass, w.isContent,
+              w.syllables.map(s => s.relativeStress).join(''));
+}
+
+// The dependency tree
+for (const dep of line.sentence.dependencies) {
+  console.log(`${dep.dependentName} ←${dep.dependentType}← ${dep.governorName}`);
+}
+
+// The prosodic hierarchy: IU → PP → clitic groups
+console.log(line.phonologicalHierarchy);
+
+// The weighted key stresses extracted from unit right-edges
+console.log(line.keyStresses);
+```
+
+### Rhyme utilities
+
+The rhyme classifier is exported on its own:
+
+```ts
+import { classifyRhymePair, detectScheme } from 'calliope-ts/dist/rhyme.js';
+
+classifyRhymePair('grace', 'face');
+// → { type: 'perfect', structure: 'masculine' }
+
+classifyRhymePair('picky', 'tricky');
+// → { type: 'perfect', structure: 'feminine' }
+
+detectScheme(['Mariner', 'three', 'eye', 'me']).map(r => r.letter).join('');
+// → "·A·A"   (i.e. ABCB with unrhymed lines marked ·)
+```
+
+### Key result types
+
+```ts
+interface PhonologicalScansionDetail {
+  meter: string;             // "iambic pentameter"
+  meterName: MetreName | 'free verse';
+  footCount: number;
+  scansion: string;          // "xs|wxm|wxs|xws"
+  certainty: number;         // 0–100
+  ranking?: MeterScore[];    // all candidate meters, best first
+  consensusMeter?: string;   // "aligns with stanza X" annotation
+  standaloneMeter?: string;  // pre-continuity-rename reading
+  rhythmNote?: string;       // dolnik / taktovik / accentual verdicts
+  rhyme?: { endWord: string; letter: string; type?: string; matchedLine?: number };
+  formNote?: string;         // stanza/poem form verdict
+  // … plus the raw weighted-score fields
+}
+```
+
+Lower-level functions (`parseDocument`, `assignLexicalStress`,
+`buildPhonologicalHierarchy`, `scoreMeters`, …) are exported from their
+modules under `calliope-ts/dist/*` for users who want to run or modify
+individual pipeline stages. The optional Scandroid comparison engines
+(Charles Hartman's "Corral the Weird" and "Maximize the Normal") are exported
+from `calliope-ts/dist/scandroid.js`.
+
+---
+
+## Examples
+
+**A Shakespeare sonnet** (`calliope-ts --reading sonnet130.txt`) — every line
+identified as iambic pentameter; the scheme letters spell ABAB CDCD EFEF GG;
+the stanza header reads `❡ Shakespearean Sonnet`.
+
+**A ballad quatrain:**
+
+```
+It is an ancient Mariner,
+And he stoppeth one of three.
+"By thy long grey beard and glittering eye,
+Now wherefore stopp'st thou me?
+```
+
+→ lines of iambic tetrameter / trimeter, scheme `·A·A`, and the form verdict
+`❡ ballad stanza (ABCB, 4·3)` — the rhyme scheme *and* the alternating
+4-beat/3-beat design both check out.
+
+**Accentual verse** (Wyatt, *They flee from me*) — no classical meter
+dominates and syllable counts vary, but every line carries four strong beats:
+each line is annotated `♪ 4-beat accentual`.
+
+**Amphibrachic verse** (Nabokov wrote his poem "Exile" as a demonstration
+of English amphibrachs — the `x S x` foot): stanza consensus reads the poem's
+constant one-syllable anacrusis as amphibrachic, names near-tie lines
+accordingly with `≈ continuity` notes, and reports the `aabccb` rhyme
+envelope.
+
+**Blank verse** (Frost, *Mending Wall*) — unrhymed lines, dominant iambic
+pentameter: `❡ blank verse`.
+
+---
+
+## Background and lineage
+
+**Calliope (2008).** The method implemented here originates with Gareth
+McAleese's *Calliope*, developed for his M.Sc. at the Open University
+(*"Improving Scansion with Syntax: an Investigation into the Effectiveness of
+a Syntactic Analysis of Poetry by Computer using Phonological Scansion
+Theory"*, Technical Report 2007/26, submitted 2008). McAleese's central idea:
+scansion should be computed from a line's *phonology* — the prosodic
+hierarchy and the stresses at the right edges of its units ("beginnings free,
+endings strict") — rather than from orthographic pattern-matching. Calliope TS
+re-implements that architecture on a modern Node.js stack and extends it.
+
+**Scandroid (1996/2005).** Charles O. Hartman's Scandroid, a classic
+foot-by-foot scanner (GNU GPL), is included as an optional comparison engine:
+its "Corral the Weird" and "Maximize the Normal" algorithms can be run side
+by side with the phonological scansion.
+
+**Extensions beyond McAleese.** The five-tier stress gradient with a
+zero-provision level; a unified dynamic-programming meter fitter with full
+substitution inventories (and first-class **amphibrach** support); beat
+promotion after Derek Attridge's beat/offbeat analysis; the dolnik/taktovik
+classification from Russian verse theory (Gasparov); stanza-consensus and
+anacrusis-profile naming; the rhyme and form layers; and the parse-correction
+layers for verse-specific tagging.
+
+**Data.** Lexical phonology comes from the augmented CMU dictionary published
+as `nounsing-pro` (syllabification, stress transcription, syllable structure,
+morphological stress classes). Parsing uses the FinNLP family. Dependency
+repairs use `depedits`, a TypeScript port of the DepEdit rule engine.
+
+Calliope TS is developed by **Aleksey Calvin** /
+[SilverAgePoets.com](https://www.SilverAgePoets.com), with particular care for
+verse traditions that standard English-centric tools marginalize: ternary
+meters, Russian Silver-Age forms in translation, song lyrics, and accentual
+verse.
+
+---
+
+## Scope, strengths, and honest limitations
+
+**Strengths.** Line-level stress mapping is the core competence — the Reading
+View is usable as a reading aid in itself. Ternary meters (anapest /
+amphibrach / dactyl) are first-class citizens, not afterthoughts. Accentual
+and dolnik verse get a real classification instead of a "free verse" shrug.
+Whole-poem context (stanza consensus, rhyme, form) informs line verdicts the
+way it does for human readers.
+
+**Limitations to know about.**
+- English only (the dictionary and parser are English; other languages will
+  produce nonsense rather than errors).
+- Stress-doublet words (*rebel*, *content*, names like *Hugo*) are read with
+  their dictionary stress; a rhyme-driven correction is on the roadmap.
+- Rare or foreign proper names fall back to rule-based stress guesses.
+- The form layer recognises the common stanza forms; it does not yet attempt
+  villanelle/pantoum repetition checking or syllabic forms.
+- Meter identification on single lines without context is genuinely harder
+  than with stanza context — when possible, scan whole poems.
+
+---
+
+## Development
+
+```bash
+npm run build     # tsc → dist/
+npm test          # vitest (73 tests: pipeline, stress, meters, rhyme, forms)
+npm run dev       # ts-node
+
+# Benchmark harnesses (require the annotated corpora in tests/)
+node trials/mcaleese_benchmark.mjs    # McAleese's own trial poems + expert keys
+node trials/corpus_benchmark.mjs      # litlab / prosodic / epg64 meter corpora
+```
+
+The repository's `AGENTS.md` carries a dated engineering log of every
+substantive change with its rationale and verification.
+
+---
+
+## License and credits
+
+Apache-2.0. © Aleksey Calvin Tsukanov / SilverAgePoets.com.
+
+Methodological debts: Gareth McAleese (Calliope, the phonological scansion
+procedure); Charles O. Hartman (Scandroid); Derek Attridge (beat/offbeat
+rhythm and the English dolnik); M. L. Gasparov (dolnik/taktovik taxonomy);
+Bruce Hayes, Paul Kiparsky, and the generative-metrics tradition (stress
+theory, syllable quantity, extrametricality); the CMU Pronouncing Dictionary
+and its `nounsing-pro` augmentation.

package/dist/depfix.d.ts

@@ -0,0 +1,13 @@
+interface FinDepNode {
+    label: string;
+    type: string;
+    parent: number;
+}
+/**
+ * Repair systematic en-parse attachment errors.  Returns a new deps array
+ * (same shape as en-parse's `toArray` output); on any failure returns the
+ * input unchanged.
+ */
+export declare function applyDepFixes(tokens: string[], tags: string[], deps: FinDepNode[]): FinDepNode[];
+export {};
+//# sourceMappingURL=depfix.d.ts.map

package/dist/depfix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depfix.d.ts","sourceRoot":"","sources":["../src/depfix.ts"],"names":[],"mappings":"AAiBA,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAwBhG"}

package/dist/depfix.js

@@ -0,0 +1,84 @@
+// depfix.ts — Post-parse dependency repair via DepEdit rules (the `depedits`
+// npm package, the maintainer's TypeScript port of DepEdit).
+//
+// Runs AFTER en-parse, complementing the pre-parse tag corrections in
+// tagfix.ts: tagfix repairs what the tagger got wrong before the tree is
+// built; this pass repairs systematic attachment errors en-parse makes even
+// with correct tags.  Rules are written in DepEdit's declarative format
+// (definitions ⟶ relations ⟶ actions, tab-separated) over en-parse's own
+// label space (DOBJ/NSUBJ/DEP/…), so the round-trip is lossless and every
+// rule is independently testable.
+//
+// The rule set is deliberately small and evidence-based — each rule cites the
+// observed failure it corrects.  `depedits` is ESM-only; it is loaded lazily
+// and failures degrade gracefully (the unrepaired parse is still a parse).
+import { createRequire } from 'module';
+// Observed failure (probe: "I had quit the programming paradigm"): en-parse
+// attaches BOTH nouns of a noun compound to the verb as parallel objects
+// ("programming ←DOBJ← quit", "paradigm ←DOBJ← quit"), and leaves the
+// determiner dangling on the first noun as generic DEP.  The repairs:
+//   1. Two adjacent common nouns sharing a governor with the same object
+//      relation → the first is a compound modifier (AMOD) of the second.
+//   2. A determiner left as DEP on a noun that has become a modifier →
+//      re-attach it as DET to that noun's head (the true NP head).
+const CALLIOPE_DEP_FIXES = [
+    'xpos=/NNS?/&func=/DOBJ|IOBJ/;xpos=/NNS?/&func=/DOBJ|IOBJ/;xpos=/VB.*/\t#3>#1;#3>#2;#1.#2\t#2>#1;#1:func=AMOD',
+    'xpos=/DT/&func=/DEP|EXT/;xpos=/NNS?/&func=/AMOD/;xpos=/NNS?.*/\t#2>#1;#3>#2\t#3>#1;#1:func=DET',
+].join('\n');
+let engine;
+function loadEngine() {
+    if (engine !== undefined)
+        return engine;
+    try {
+        // This package compiles to ESM, where bare `require` does not exist, and
+        // the parse path is synchronous, so dynamic import() is not an option:
+        // createRequire gives a sync loader, and since `depedits` is itself
+        // ESM-only this resolves via Node's require(esm) (≥20.17 / ≥22.12).  On
+        // older runtimes it throws and the repair pass degrades to a no-op (the
+        // unrepaired parse is still a parse).
+        const req = createRequire(import.meta.url);
+        const { DepEditEngine } = req('depedits');
+        const e = new DepEditEngine();
+        e.loadIniString(CALLIOPE_DEP_FIXES);
+        engine = e;
+    }
+    catch {
+        engine = null;
+    }
+    return engine;
+}
+/**
+ * Repair systematic en-parse attachment errors.  Returns a new deps array
+ * (same shape as en-parse's `toArray` output); on any failure returns the
+ * input unchanged.
+ */
+export function applyDepFixes(tokens, tags, deps) {
+    const e = loadEngine();
+    if (!e || tokens.length === 0 || deps.length !== tokens.length)
+        return deps;
+    try {
+        const conllu = tokens.map((tok, i) => {
+            const head = deps[i].parent >= 0 ? deps[i].parent + 1 : 0;
+            const safe = tok.replace(/\s/g, '_') || '_';
+            return `${i + 1}\t${safe}\t${safe}\t_\t${tags[i] || '_'}\t_\t${head}\t${deps[i].label || 'DEP'}\t_\t_`;
+        }).join('\n') + '\n\n';
+        const out = e.process(conllu);
+        const fixed = deps.map(d => ({ ...d }));
+        for (const row of out.split('\n')) {
+            const cols = row.split('\t');
+            if (cols.length < 10)
+                continue;
+            const idx = parseInt(cols[0], 10) - 1;
+            if (!(idx >= 0 && idx < fixed.length))
+                continue;
+            const head = parseInt(cols[6], 10);
+            fixed[idx].parent = Number.isFinite(head) ? head - 1 : fixed[idx].parent;
+            if (cols[7] && cols[7] !== '_')
+                fixed[idx].label = cols[7];
+        }
+        return fixed;
+    }
+    catch {
+        return deps;
+    }
+}

package/dist/display.d.ts

@@ -0,0 +1,38 @@
+import { ClsWord, LineResult } from './types.js';
+export declare function renderUnifiedDisplay(result: LineResult, rawLine?: string): string;
+export declare function renderLegend(): string;
+/**
+ * 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 declare function renderFullLegend(): string;
+/** One input line with its (1+) parsed sentence results. */
+export interface ReadingLine {
+    raw: string;
+    results: LineResult[];
+}
+/** A stanza: a run of consecutive non-blank input lines. */
+export interface ReadingStanza {
+    lines: ReadingLine[];
+}
+/**
+ * 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 declare function projectStressOntoLine(rawLine: string, words: ClsWord[]): string;
+/**
+ * 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 declare function renderReadingView(stanzas: ReadingStanza[]): string;
+//# sourceMappingURL=display.d.ts.map

package/dist/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,OAAO,EAMP,UAAU,EAGX,MAAM,YAAY,CAAC;AAqJpB,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAkPjF;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAUrC;AAuHD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAsBzC;AAqCD,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAuC/E;AAmMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAsDlE"}