calliope-ts 0.0.1 → 0.0.3

package/README.md

@@ -1,31 +1,21 @@
 # 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** is a phonological poetry-scansion toolkit for TypeScript / Node.js. Hand it a poem (or a single line), and it will tell you — and *show* you — how that verse actually moves: which syllables carry weight and how much, where the beats fall, what meter each line is in and how confidently, what rhymes with what, and what form the stanzas add up to.
+
+The premise is that meter is something you *recover from pronunciation*, not something you stamp onto spelling. So Calliope reads a line roughly the way an attentive reader does: it first works out how the words would be said aloud — dictionary stress, the way phrases clump, where the voice peaks at a clause-end — and only then looks for the regular beat that saying settles into. This approach has a name in the linguistics literature, **phonological scansion**, and the bulk of this README is about what that means and how the toolkit puts it to work.
 
 ```
 $ 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
+He happens to be a French poet, that thin,     ← each syllable is tinted by how
+book-carrying man with a bristly gray chin;        much stress it carries (see below)
 ...
 
-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)
+Stress Maps & Meter  — top-3 candidate meters per line
+  S1L1   nsw|xwx|msw ‖ xs    amphibrachic tetrameter  (amph 1.20 · iamb 1.14 · anap 1.13)  A
+  S1L2   m-mw|wsx|xmw|ms     amphibrachic tetrameter  ≈ continuity; standalone: dactylic tetrameter  A
   ...
 ```
 
@@ -36,9 +26,12 @@ Stress Maps & Meter  — top-3 fit scores per line
 - [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)
+- [What "phonological scansion" means](#what-phonological-scansion-means)
+- [The pipeline, stage by stage](#the-pipeline-stage-by-stage)
+- [A note on rules vs. constraints](#a-note-on-rules-vs-constraints)
 - [Programmatic usage (API)](#programmatic-usage-api)
 - [Examples](#examples)
+- [How it compares to other scanners](#how-it-compares-to-other-scanners)
 - [Background and lineage](#background-and-lineage)
 - [Scope, strengths, and honest limitations](#scope-strengths-and-honest-limitations)
 - [Development](#development)
@@ -48,15 +41,13 @@ Stress Maps & Meter  — top-3 fit scores per line
 
 ## 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).
+Requires **Node.js ≥ 20** (≥ 22 recommended — one optional stage, the dependency-tree repair, uses Node's `require(esm)` support and simply switches itself off on older runtimes).
 
 ```bash
 # As a global CLI tool
 npm install -g calliope-ts
 
-# Or as a library in your project
+# Or as a library inside your own project
 npm install calliope-ts
 ```
 
@@ -79,14 +70,14 @@ 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
+# 3. Reading view — the poem itself, syllables tinted by stress
+#    (the nicest way to read a whole poem; first option in the CLI; 
+or add -r or --reading)
 
 # 4. Pipe text in
 cat poem.txt | calliope-ts --reading
 
-# 5. Interactive menu (run with no arguments in a terminal)
+# 5. Interactive menu (run without typing arguments in a terminal each time)
 calliope-ts
 ```
 
@@ -119,31 +110,34 @@ core representation everything else is built on):
 | `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.
+`xs|wxm|wxs|xws` — with: 
+`|` marking foot boundaries;
+`‖` a strong caesura (aka syntactic pause) at major phonological/clausal or punctuation breaks;
+`¦` a lighter phrase break;
+`-` a "silent beat" inserted to neutralize a stress clash wherever two strongly-stressed syllables would otherwise collide, it forces the second to await its turn.
 
 ### Meter lines
 
+In the reading view each verse-line gets a single summary line. 
+Reading one such line left to right:
+
 ```
 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.
+- **`amphibrachic tetrameter`** — the line's meter: foot type + count.
 - **`(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.
+  alone, fits dactylic a hair better; but if most of the other lines in the same stanza are amphibrachic and the line fits amphibrachic nearly as well as it fits dactylic, the primary reading is promoted to the stanza-dominant base meter, while the line-prevalent meter is co-registered as the "standalone" top fit via an added 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).
+- **`♪ 4-beat accentual`** / `♪ 3-ictus dolnik` — a *rhythm note*: if the stanza
+  does not appear to be accentual-syllabic, but keeps a constant count of strong beats
+  with varying syllable counts (see "Beyond classical meters" below), it is marked as acentual.
 - **`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`,
@@ -151,7 +145,7 @@ S1L2   m|-mww|sxx|mwm|s   amphibrachic tetrameter   (dact 1.21 · amph 1.17 ·
 - **`❡ 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
+- **Certainty / fit %** (detailed view) — the share of the line realized by
   clean, unsubstituted feet, tempered by phrase-edge agreement. A perfectly
   regular line reads 100%; real verse usually lands between 50 and 90.
 
@@ -159,99 +153,52 @@ S1L2   m|-mww|sxx|mwm|s   amphibrachic tetrameter   (dact 1.21 · amph 1.17 ·
 
 ## 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.
+Most automatic scanners pattern-match syllable counts against meter templates, or "from the outside in": count syllables, then match the count and a guessed stress pattern against a list of meter templates. Calliope TS instead follows the **phonological scansion** method. Phonological scansion works "from the inside out": it derives the line's normative spoken prominence first, then fits meters to it.
+
+Two simple principles carry a lot of the work here, both articulated in Bruce Hayes and Abigail Kaun's study of how words are set to music (*The Role of Phonological Phrasing in Sung and Chanted Verse*, 1996):
+
+1. **The ends of phonological units is what matters the most (in English, at least).**: Stresses at the *right edges* of prosodic units are more reliable metrical evidence. Generative metrics has long summarized this as **"beginnings free, endings strict."**
+
+2. **Bigger units matter more.**
+So, a stress at the end of a whole intonational unit is stronger evidence than one at the end of a phonological phrase, which is stronger evidence than the distribution of a given clitic phrase, which is more significant than the pattern of an individual word (however longer polysyllabic words may likewise hold more "weight" here). And in English as a whole, the pattern generally leans to the right (with certain significant exceptions, like numerous classes of compound expressions). But this bias as such aligns with the infamous iambic inclination.
+
+Bruce Hayes himself (2005) and Gareth McAleese (2007/2008) built the first faithful algorithmic/computational implementations of a verse scansion procedure around those two ideas. Calliope TS re-implements that architecture on a modern JavaScript/TypeScript stack, while attempting to push it into distinctive directions. Among these: deliberately looser pre-attunement to standard iamb-centered English canons (while preserving and seeking to refine English phonological alignment accuracy); better accommodation of World poetry in meter-matching English translation (in other words, English canon levels of iambic base meter predominance should not be pre-assumed for Englished World (aka "Worldish") poetry canons); likewise, the mechanics of Calliope TS proceed from a choice not to essentialize ternary meters as inherently rare solely from English canon distributions (statistical fatalism); we, furthermore, aim to extend scansion accuracy over accentual verse forms; and, beyond scansion itself, hope to gradually incorporate nuanced and diversified identification of a broad range of poetic forms and devices (currently supported: rhyme types; in the future: alliterations, anaphoras, trope/cliche identifications, and more). 
+
+
+The current pipeline has eight stages.
+
+**1. Grammatical parsing.** 
+The line is tokenized, part-of-speech tagged, and dependency-parsed — that is, the engine works out which word grammatically governs which (subject of what verb, object of what preposition) — using the FinNLP family of libraries (`lexed`, `en-pos`, `en-parse`). Two correction layers sit inside this stage,
+First, because poetry tends to break part-of-speech and grammatical dependency taggers in predictable ways, a *tag-repair* pass fixes systematic errors before the dependency tree is built (this appropriately accounts for rare exotics and awkward/shifty commonplaces alike: from archaic forms like *thou/thy/doth/wherefore*, to the pronoun *I*, to perfect-tense participles like *had quit*).
+Then we leverage a *tree-repair* pass (using the [depedits](https://www.npmjs.com/package/depedits) rule engine, our TypeScript port of the DepEdit library, originally in Python), which fixes systematic phrasal role attachment errors (e.g. noun compounds parsed as double objects, and the like). Hyphenated compounds and contractions (like *we'll*, *don't*, archaic *fix'd*, etc) are re-merged into single metrical words.
+
+**2. Lexical stress.** 
+Every word is looked up for its pronunciation — syllable count, primary/secondary/unstressed pattern, syllable weights, vowel quantities — via our [nounsing-pro](https://www.npmjs.com/package/nounsing-pro) NLP toolkit, build over a full-scope CMU dictionary augmented with phonological and morphological data: syllable count, stress pattern (primary / secondary / unstressed), syllable weights, consonant types, morphological complexity and
+vowel quantities. Words not in the dictionary go through a morphological fallback (strip a productive suffix, look up the stem, restore) coupled with a quantity-sensitive English Stress Rule. Poetic elisions are honored: *heav'n* is parsed as one syllable, so is *o'er*, *th'expense* as two, *'tis/'twas* reduces, while archaic *-'d* / *-'st* forms (*fix'd*, *stopp'st*) retain their elided syllable counts.
+
+**3. The prosodic hierarchy.**
+Words are grouped the way speech groups them, in the nested structure linguists call the prosodic hierarchy (Selkirk 1978; Hayes 1989):
+Each content word attracts its function-word satellites into a **clitic group** (CP); clitic groups are joined into **phonological phrases** (PP) in accordance with syntactic inter-dependencies and primacies parsed earlier; phrases are organized into **intonational units** (IU) bounded by major punctuation or/and delineation. Crucially, the **line is the scansion domain**: a verse line containing several grammatical sentences is still parsed as a singular metrical unit (the internal full stops are treated as strong caesurae).
 
 **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.
+Several well-established rules of *English stress* mediate dictionary-derived lexical stresses within the consolidated phonological/phrasal context: primarily, the **compound stress rule** (left element generally stressed, *CITY hall*, with various exceptions), the **nuclear stress rule** (the last content word of an intonational unit receives a stress boost), 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.**
+Following generative metrics, the stresses at the *right edges* of prosodic units are treated as more reliable — 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 > short word ), and meters that place beats on those key stresses are promoted.
+
+**6. Meter fitting.**
+For each of seven candidate metrical foot types — iambic, trochaic, anapestic, dactylic, amphibrachic, bacchic, spondaic — the engine finds the optimal division of the line into feet, using that meter's inventory of most plausible variations/divergences: inversions at line-start or after a caesura, pyrrhic and spondaic foot substitutions, catalexis (truncated final foot), anacrusis (extrametrical upbeat), feminine endings, acephalous openings, and so forth. Each syllable is scored against the metrical position it lands in (a strong syllable in a beat slot
+is ideal; while a reduced clitic forced onto a beat is perhaps the heaviest cardinal violation). An additional **promotion** rule (drawn from Derik Attridge) lets a weak syllable carry a beat when it is flanked by even weaker ones (*"happens to BE a French poet"*).
 
 **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.
+The winning meter is not simply the top raw score:
+- **Ternary siblings** (anapest / amphibrach / dactyl meters) may sometimes fit a line via an *identical* distribution of beats — the difference being only where one might draw the foot boundaries. In such a situation, the base meter determination is decided by which foot division avoids slicing through words and best aligns with the line's pauses.
+- **Stanza consensus**: each stanza's dominant meter is identified. An additional consideration is taken into account for ternary meters at this point: *anacrusis profile* — how many unstressed syllables are found at the beginning of a given line, and the stanza as a whole (a sensible heuristic suggested by Russian metrics).
 
 **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.
+If a stanza's syllable counts vary significantly while its strong-beat count stays constant, the stanza is read as **accentual verse** , rather than classically footed accentual-syllabic (aka syllabotonic), and labeled as (`n-beat accentual`).
+
+Alongside this, a **rhyme layer** classifies every line-end pair (perfect / rich / family / slant /eye / … rhymes, in masculine / feminine / dactylic shapes), detects the poem's rhyme scheme (if discernible), as well as its apparent **poetic form** (if documented by us). For now, the range of supported forms is very limited and the mechanics of discernment leave much to be desired. As of this version, the engine may (when particularly inspired) identify a ballad stanza, blank verse (unrhymed iambic pentameter), couplets, quatrains, limericks, rhyme royal, Shakespearean or Petrarchan sonnets, and Dante-style terza rima.
 
 ---
 
@@ -353,20 +300,15 @@ interface PhonologicalScansionDetail {
 }
 ```
 
-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`.
+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 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:**
 
@@ -377,82 +319,42 @@ And he stoppeth one of three.
 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.
+→ 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`.
+**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.
+**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`.
+**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.
+The method implemented here substantially follows the example set by Gareth McAleese's *Calliope* (2007.2008), 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). For it, McAleese devises a computational scansion framework substantially grounded in the phonological scansion methodologies of UCLA's renowned linguist and phonologist **Bruce Hayes**, developed by him across the 1980s, 90s, and 2000s — most relevantly in *Extrametricality and English Stress* (1982), *The Phonology of Rhythm in English* (1984), *The Prosodic Hierarchy in Meter* (1989), the *Metrical Stress Theory* (1995), and *The Role of Phonological Phrasing in Sung and Chanted Verse* with Abigail Kaun (1996). Hayes in turn built on the groundwork laid by Halle & Chomsky, Liberman & Prince, and Kiparsky (some of the seminal Generative Metrics, Optimality Theory, and related domains. Most pertinent to approach taken up by McAleese (as well as ourselves presently) is Hayes's   work from the early 1990s onward, in which he drew increasingly on the nascent **Optimality Theory** (OT) (much credit to Prince & Smolensky, whose *Optimality Theory: Constraint Interaction in Generative Grammar*, 1993/2002, much enriched the empirical toolkit of generative grammar-adjacent theory domains). In the 2000s Hayes would contribute to placing OT onto the more precise rails of **MaxEnt** (Maximum Entropy) methods. McAleese's work, however, preceded this turn. Backing up somewhat to peruse the field, it is worth acknowledging the remarkable breadth of synthesis McAleese draws on, which beyond those above-named, harnesses the influence of Paul Kiparsky (e.g. *The Rhythmic Structure of English Verse*, 1977), Kristin Hanson (*A Parametric Theory of Poetic Meter*, 1996), the prosodic-phrasing and stress-shift related work of Elisabeth Selkirk (1978), as well as studies by Richard Cureton (1992), Peter Groves (1998), and many others (see McAleese's paper at https://oro.open.ac.uk/90197/ for a full bibliography).
 
----
+| Source | What it grounds in Calliope |
+|---|---|
+| Hayes & Kaun (1996) | the core method: right-edge key stresses, weighted by prosodic-unit size (stage 5) |
+| Hayes (1989), *Prosodic Hierarchy in Meter* | the CP → PP → IU phrasing (stage 3) |
+| Hayes (1982), *Extrametricality* | extrametrical syllables and the OOV English Stress Rule (stage 2) |
+| Chomsky & Halle (1968); Liberman & Prince (1977); Hayes (1984) | the lexical and phrasal stress rules — compound, nuclear, clash (stage 4) |
+| Prince & Smolensky (1993/2002); Hayes et al., MaxEnt | the constraint-based, weighted meter fitter (stages 5–7) |
+| Selkirk (1978) | the phonological phrase as a prosodic constituent (stage 3) |
+| Attridge, *The Rhythms of English Poetry* / *The Rhythms of the English Dolnik* | beat/offbeat promotion (stage 6) and the dolnik (stage 8) |
+| Gasparov, *A History of European Versification* | the dolnik / taktovik / accentual taxonomy (stage 8) |
+| McAleese (2008) | the core outline for the scansion procedure, with further solutions drawn by us from Hayes 2008 & Prosodic (MaxEnt weighing), as well as original extrapolations |
+
+**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.
 
-## Scope, strengths, and honest limitations
+Calliope TS is developed by **Aleksey Calvin** / [SilverAgePoets.com](https://www.SilverAgePoets.com)
 
-**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.
+- 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 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.
 
 ---
 
@@ -468,18 +370,12 @@ 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.
+My email: alekseycalvin@gmail.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.
+Methodological and conceptual debts: Bruce Hayes (1982/1984/1995/1996 with Abigail Kaun/2005) (the phonological scansion procedure as such, extrametricality insights, text-setting methodologies, MaxEnt OT, and who knows what else), Gareth McAleese (for a single 2008 paper, for detailing the original Calliope implementation, for exhibiting a remarkable field-spanning purview, an uncanny industriousness, and an uncommon – perhaps a tad obsessive – dedication to testing, refining, fusing, and extending all sorts of methodologies in a single-minded pursuit of bringing constraint-based computational scansion far beyond the best documented practices and results at that time; and for so obviously succeeding, if only to seemingly vanish from the field as abruptly and unreservedly as he entered and absorbed it*); Charles O. Hartman (Scandroid); Claire Moore Cantwell (morphological/phonological tagging algorithms), Austin Pursley (implementing finer-grained rhyme-matching heuristics over a corpus), Allison Parrish (Pronouncing-py and being a real life computational poet hero), Derek Attridge (beat/offbeat rhythm theory and insightful writings on the English dolnik); M. L. Gasparov (dolnik/taktovik taxonomy); the compilers of the CMU Pronouncing Dictionary; the makers of Prosodic (Heuser et al, for establishing an admirable state-of-the-art to compare against, differentiate from, and hopefully surpass in due time, in select ways), as well as broader generative-metrics, constraint-based metrics, and OT traditions, including Kiparsky, Prince & Smolensky, Groves, Blumenfeld, Lilja, Chomsky & Halle, Fabb & Halle (rule-based grid scansion theory), Einarsson (Metremic theory), Russom (Universalist metrics), K. M. Ryan (gradient syllable weight), big daddy Jakobson who had once roped the whole world with subtle strings and often hung out with Mayakovsky, and many others.
+*Gareth McAleese: If you're reading this, please do email me!

package/dist/caesura.d.ts

@@ -0,0 +1,33 @@
+import { ClsWord, IntonationalUnit } from './types.js';
+export type CaesuraKind = 'hard' | 'soft';
+/** A caesura with its graded boundary strength (0..1, NSBR-scaled), so the display
+ *  can colour the mark by how strong the underlying prosodic break is. */
+export interface CaesuraInfo {
+    kind: CaesuraKind;
+    strength: number;
+}
+/**
+ * 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.
+ *  • 'soft' — a single INFERRED medial caesura for a punctuation-free line.
+ *    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.
+ */
+export declare function computeCaesurae(words: ClsWord[], ius: IntonationalUnit[], scansion?: string): Map<number, CaesuraInfo>;
+/**
+ * The words that immediately PRECEDE a caesura in a line — i.e. each word whose
+ * cumulative syllable count lands exactly on a caesura position.  Used by the
+ * rhyme layer for pre-caesural internal-rhyme detection.  Returned in linear
+ * (reading) order; the caesura kind is paired so callers can weight hard vs
+ * inferred breaks if they wish.
+ */
+export declare function preCaesuralWords(words: ClsWord[], ius: IntonationalUnit[], scansion?: string): {
+    word: ClsWord;
+    kind: CaesuraKind;
+}[];
+//# sourceMappingURL=caesura.d.ts.map

package/dist/caesura.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caesura.d.ts","sourceRoot":"","sources":["../src/caesura.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIvD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C;0EAC0E;AAC1E,MAAM,WAAW,WAAW;IAAG,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;CAAE;AAyCrE;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAuGtH;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,EAAE,CAYxC"}