calliope-ts 0.0.2 → 0.0.4

package/README.md

@@ -1,18 +1,8 @@
-# Calliope TS
+# Calliope TS 0.0.4
 
-**Calliope TS** is a phonological poetry scansion toolkit for TypeScript / Node.js. 
+**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.
 
-Its name, of course, recalls a muse. 
-Hand to this muse a song or verse, 
-And she might show you how it curves, 
-Which syllables hold weight in time, 
-How much of it, and where a rhyme, 
-Which meter dances through each line,
-And where should land each beat
-Your voice might drawl, or music drawn...
-She even knows poetic form!
-
-The premise of this toolkit is that rhythm, and therefore also meter, is much more reliably *recovered from pronunciation* than from text as such. What?! But there's no Text-to-Speech here?! (Sorry!) A lapse? A paradox? Nah. Instead, Calliope parses a stanza or verse, reproducing roughly how an attentive (but silent) reader might do so: first, working out how the words are likely to be said aloud — deduced by following contextual patterns, cohering a syntax, wielding phonotactics, evading constraints, gathering prosody, accounting for the ways phrases clump or bounce, for how a voice might subtly perk over clause-ends, and all the rest of it; and only thereafter scanning for what sort of rhythms a phrase such as that might be spectrally reaching for, or settling into. The scholars dwelling on Generative Metrics, a liminal little field somewhere in-between linguistics, phonetics, and literary studies, call this sort of approach **phonological scansion**, and the bulk of this README is about what that means and how the toolkit puts it to work.
+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
@@ -89,11 +79,15 @@ cat poem.txt | calliope-ts --reading
 
 # 5. Interactive menu (run without typing arguments in a terminal each time)
 calliope-ts
+
+# 6. Run the alternative "Clio" parse (powered by the legacy FinNLP suite)
+calliope-ts --clio poem.txt
 ```
 
 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.
+view, a **legend** explaining every symbol and colour, and an option to 
+"Ask Clio instead" for the alternative parse.
 
 There are two display modes:
 
@@ -178,7 +172,7 @@ Bruce Hayes himself (2005) and Gareth McAleese (2007/2008) built the first faith
 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,
+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 `udpipe-node` (our Node/JS/WASM port of UDPipe), now generating Universal Dependencies (UD) trees and morphological features. (For legacy comparison, the toolkit's built-in "Clio" alternate mechanics persist in using the FinNLP family of libraries (`lexed`, `en-pos`, `en-parse`) instead). A conversion layer seamlessly translates UD tags into the Penn Treebank tags our prosody expects. 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.
 
@@ -219,6 +213,10 @@ import {
   analyzeStanzas,          // poem text → LineResult[][]  (per stanza, per line)
   analyzeText,             // poem text → LineResult[]    (flat)
   analyzeReadingDocument,  // poem text → ReadingStanza[] (keeps verbatim lines)
+  // The legacy/alternate "Clio" engine equivalents (using FinNLP):
+  analyzeStanzasClio,
+  analyzeTextClio,
+  analyzeReadingDocumentClio,
 } from 'calliope-ts';
 ```
 
@@ -362,7 +360,7 @@ Calliope TS is developed by **Aleksey Calvin** / [SilverAgePoets.com](https://ww
 ---
 
 **Limitations to know about.**
-- English only (the dictionary and parser are English; other languages will produce nonsense rather than errors).
+- English only (the dictionary and phonological rules are English; while the UDPipe backend natively supports multilingual parsing, 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.
 
@@ -384,8 +382,22 @@ node trials/corpus_benchmark.mjs      # litlab / prosodic / epg64 meter corpora
 
 ## License and credits
 
-Apache-2.0. © Aleksey Calvin Tsukanov / SilverAgePoets.com.
-My email: alekseycalvin@gmail.com
-
-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.
+Apache-2.0. © Aleksey Calvin Tsukanov / SilverAgePoets.com. <br>
+My email: alekseycalvin@gmail.com <br>
+
+Methodological and conceptual debts: 
+- Michael Wagner (Prosody and Recursion, MIT, 2005) (for further clarifying the inter-relational nuances of prosody and syntax).
+- Manfred Krifka (2001/2002) (for so poignantly elucidating NSR and CSR beyond SPE).
+- 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),
+- Milan Straka and the UDPipe project (for the robust neural parsing architecture now driving the core mechanics), 
+- 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. <br>
 *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"}

package/dist/caesura.js

@@ -0,0 +1,202 @@
+// caesura.ts — Caesura placement, shared by the display and rhyme layers.
+//
+// A caesura is the line's medial pause.  Two kinds are distinguished:
+//  • 'hard' — an overt break at an Intonational-Unit boundary (comma, dash,
+//    colon, semicolon …): the punctuation projection.
+//  • 'soft' — a single INFERRED medial caesura for a punctuation-free line
+//    (Kiparsky 1975, via McAleese: "phonological phrasing determines the
+//    location of caesurae in verse").
+//
+// Extracted from display.ts (2026-06-13) so the rhyme layer can find the words
+// that immediately precede caesurae (for pre-caesural internal-rhyme detection)
+// without importing the display module.  Pure analysis — no colour/chalk here.
+import { isPunctuation } from './parser.js';
+import { computeBoundaries } from './calliope/boundaries.js';
+/** Foot-boundary syllable indices from a scansion string (cumulative syllable
+ *  count after each foot; silent beats '-' are not syllables). */
+function footBoundarySet(scansion) {
+    const set = new Set();
+    let c = 0;
+    for (const foot of scansion.split('|')) {
+        for (const ch of foot)
+            if ('xwnms'.includes(ch))
+                c++;
+        set.add(c);
+    }
+    return set;
+}
+// A new phonological/syntactic phrase opens at these POS tags: prepositions &
+// subordinators (IN), infinitival "to" (TO), coordinators (CC), wh/relativizers,
+// verb-particles (RP), and the predicate's verb/modal.  The major medial caesura
+// of a line falls immediately BEFORE such a word — far more reliably read off the
+// (robust) POS tags than off FinNLP's (noisy) phonological-phrase grouping, which
+// mis-bracketed e.g. "The epic | feast…".  Determiners/articles are excluded (they
+// continue a phrase a preposition already opened: "as | one empty bag").
+const PHRASE_ONSET_POS = new Set([
+    'IN', 'TO', 'CC', 'WDT', 'WP', 'WP$', 'WRB', 'RP',
+    'VB', 'VBD', 'VBG', 'VBN', 'VBP', 'VBZ', 'MD',
+]);
+// Directional/spatial adverbs that open a phrase ("snowed-in OUT of many routes",
+// "drifting DOWN to sleep").  FinNLP often tags these RB rather than RP/IN, so the
+// POS set alone misses them; a small curated lemma list recovers them with low
+// over-fire risk (a generic RB like "very"/"quickly" is NOT a phrase onset).
+const DIRECTIONAL_ONSET = new Set([
+    'out', 'in', 'up', 'down', 'off', 'away', 'back', 'forth', 'over',
+    'around', 'along', 'through', 'apart', 'aside', 'onward', 'onwards',
+]);
+/** True if a word opens a new phonological/syntactic phrase (a caesura candidate). */
+function isPhraseOnset(w) {
+    if (PHRASE_ONSET_POS.has(w.lexicalClass))
+        return true;
+    return w.lexicalClass === 'RB' && DIRECTIONAL_ONSET.has(w.word.toLowerCase());
+}
+/**
+ * Caesura positions for a line, keyed by the syllable index AFTER which the pause
+ * falls (= number of syllables to its left).
+ *  • 'hard' — an overt break at an Intonational-Unit boundary.
+ *  • '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 function computeCaesurae(words, ius, scansion) {
+    const caes = new Map();
+    // Graded boundary strength (Wagner Ch.4–5) keyed by syllable index, so each
+    // caesura carries the strength of its underlying ϕ/ι break — used both to COLOUR
+    // the mark and to gate strong-ϕ hard caesurae on a line-relative threshold.
+    const bounds = computeBoundaries(words, ius);
+    const strengthAt = new Map();
+    for (const b of bounds.phi) {
+        const prev = strengthAt.get(b.syllableIndex) ?? 0;
+        if (b.strength > prev)
+            strengthAt.set(b.syllableIndex, b.strength);
+    }
+    const strOf = (syl) => strengthAt.get(syl) ?? 0;
+    const setHard = (syl) => caes.set(syl, { kind: 'hard', strength: Math.max(0.6, strOf(syl)) });
+    // Caesurae must sit on FOOT BOUNDARIES (when the scansion is known).  The line's
+    // metrical feet ARE the scansion's own segmentation, so a break that falls mid-
+    // foot has no metrical reality — it merely fragments a foot (often into a lone
+    // monosyllable: "But ‖ Oh ‖ ye…") and it made the reading view disagree with the
+    // detailed "Feet:" view, which already marks foot-edge breaks only.  Punctuation
+    // is a caesura CANDIDATE, never an override: an IU boundary that does not land on
+    // a foot edge is dropped (the soft-caesura fallback below then offers one medial,
+    // foot-aligned break if the line is long enough).
+    const footEdges = scansion ? footBoundarySet(scansion) : null;
+    const iuOf = new Map();
+    for (let i = 0; i < ius.length; i++) {
+        for (const pp of ius[i].phonologicalPhrases) {
+            for (const cg of pp.cliticGroups)
+                for (const tok of cg.tokens)
+                    iuOf.set(tok, i);
+        }
+    }
+    let cum = 0;
+    let prevIu;
+    let prevWasContentful = false;
+    const onsetPositions = [];
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass) || w.syllables.length === 0) {
+            // A COMMA is an overt medial pause — the canonical caesura marker — but in
+            // the Match-Theory hierarchy it is only a ϕ (minor) break, NOT an ι boundary
+            // (dash/colon/semicolon DO project an ι, so those are caught by the IU test
+            // below).  So detect a comma here directly: a comma after a contentful word,
+            // landing on a foot edge, is a hard caesura.  (Without this, the comma→ϕ
+            // reclassification silently dropped every comma caesura, taking pre-caesural
+            // and caesural internal-rhyme detection with it.)
+            if (prevWasContentful && (w.lexicalClass === ',' || w.word === ',')
+                && (!footEdges || footEdges.has(cum))) {
+                setHard(cum);
+            }
+            continue;
+        }
+        const iu = iuOf.get(w);
+        if (prevIu !== undefined && iu !== undefined && iu !== prevIu
+            && (!footEdges || footEdges.has(cum))) {
+            setHard(cum); // IU boundary landing on a foot edge → hard caesura
+        }
+        // A phrase-onset word that is NOT the line's first word opens a candidate
+        // caesura immediately before it.
+        if (prevWasContentful && isPhraseOnset(w))
+            onsetPositions.push(cum);
+        cum += w.syllables.length;
+        prevIu = iu;
+        prevWasContentful = true;
+    }
+    const total = cum;
+    // STRONG-ϕ hard caesura (Wagner Ch.5): a ϕ boundary whose NSBR-scaled strength
+    // clears a line-relative threshold — a major medial break after a long branching
+    // phrase — is a hard caesura even without punctuation, provided it lands on a foot
+    // edge and is medial.  Threshold is relative (strength is already line-normalised),
+    // so a comma after a short phrase does NOT trigger one.
+    if (total >= 8) {
+        const lo = Math.max(2, Math.ceil(total / 3));
+        const hi = Math.floor((2 * total) / 3);
+        for (const b of bounds.phi) {
+            const c = b.syllableIndex;
+            if (c < lo || c > hi)
+                continue;
+            if (footEdges && !footEdges.has(c))
+                continue;
+            if (caes.has(c))
+                continue;
+            if (b.strength >= 0.75)
+                caes.set(c, { kind: 'hard', strength: b.strength });
+        }
+    }
+    // Infer ONE medial caesura only when the line carries no overt (hard) break.
+    // Prefer the STRONGEST candidate boundary, tie-broken by nearness to the midpoint.
+    if (caes.size === 0 && total >= 8 && onsetPositions.length > 0) {
+        const mid = total / 2;
+        const lo = Math.max(2, Math.ceil(total / 3));
+        const hi = Math.floor((2 * total) / 3);
+        let best = -1, bestStr = -1, bestDist = Infinity;
+        for (const c of onsetPositions) {
+            if (c < lo || c > hi)
+                continue; // medial third only
+            if (footEdges && !footEdges.has(c))
+                continue; // align to a foot boundary
+            const str = strOf(c);
+            const d = Math.abs(c - mid);
+            if (str > bestStr + 1e-6 || (Math.abs(str - bestStr) <= 1e-6 && d < bestDist)) {
+                bestStr = str;
+                bestDist = d;
+                best = c;
+            }
+        }
+        if (best > 0)
+            caes.set(best, { kind: 'soft', strength: Math.max(0.25, bestStr) });
+    }
+    // A caesura is a MEDIAL pause: a line-terminal comma/IU close lands at the last
+    // syllable (cum == total) and is the line break's own boundary, not a caesura.
+    // Dropping it here keeps every consumer consistent — the detailed view used to
+    // print a spurious trailing '‖' the reading view (correctly) never showed, and
+    // the rhyme layer would have double-counted the end word as "pre-caesural".
+    caes.delete(total);
+    return caes;
+}
+/**
+ * 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 function preCaesuralWords(words, ius, scansion) {
+    const caes = computeCaesurae(words, ius, scansion);
+    if (caes.size === 0)
+        return [];
+    const out = [];
+    let cum = 0;
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass) || w.syllables.length === 0)
+            continue;
+        cum += w.syllables.length;
+        const info = caes.get(cum);
+        if (info)
+            out.push({ word: w, kind: info.kind });
+    }
+    return out;
+}

package/dist/calliope/boundaries.d.ts

@@ -0,0 +1,19 @@
+import { ClsWord, IntonationalUnit } from '../types.js';
+export interface BoundaryInfo {
+    level: 'kappa' | 'phi' | 'iota';
+    strength: number;
+    raw: number;
+    syllableIndex: number;
+}
+export interface LineBoundaries {
+    /** ϕ boundaries in document order: phi[k] is the boundary OPENING the k-th ϕ.
+     *  phi[0] is the line's left edge (strength 0 — not a real internal break). */
+    phi: BoundaryInfo[];
+    /** ι boundaries in document order, same convention. */
+    iota: BoundaryInfo[];
+}
+/**
+ * Compute graded boundary strength for every ϕ and ι boundary in a line.
+ */
+export declare function computeBoundaries(words: ClsWord[], ius: IntonationalUnit[]): LineBoundaries;
+//# sourceMappingURL=boundaries.d.ts.map

package/dist/calliope/boundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries.d.ts","sourceRoot":"","sources":["../../src/calliope/boundaries.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B;mFAC+E;IAC/E,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,uDAAuD;IACvD,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAuFD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,cAAc,CAyD3F"}

package/dist/calliope/boundaries.js

@@ -0,0 +1,182 @@
+// calliope/boundaries.ts — graded prosodic boundary strength (Wagner 2005 Ch. 4–5).
+//
+// The labelled κ/ϕ/ι hierarchy is the SKELETON; this module adds the relational
+// FLESH Wagner argues the grid actually encodes — a graded boundary strength rather
+// than a categorical label.  Each ϕ/ι boundary gets a strength scaled RELATIVE to the
+// line's other boundaries (the NSBR, Normalized Scopally-determined Boundary Rank,
+// Ch. 5 §5.3): the strongest boundary in the line is 1.0, the rest fall below it.
+//
+// The raw strength of a boundary between left unit A and right unit B combines:
+//   • the categorical level (ι ≫ ϕ ≫ κ) — the SBR base rank;
+//   • punctuation coincidence — a comma/dash/colon at the boundary makes it stronger;
+//   • the LENGTH of the preceding constituent (a boundary after a long, branching
+//     phrase is stronger — Wagner Ch. 5 look-back);
+//   • clause separation — a boundary between subject|predicate or main|subordinate
+//     clause (their dependency LCA is at/near the root) is stronger;
+//   • associative coordination — a boundary internal to a same-coordinator series is
+//     WEAKER (equal-rank, flat).
+//
+// Strength feeds (a) the colored bracket rendering (display.ts) and (b) caesura
+// placement (caesura.ts): a hard caesura needs a boundary whose strength clears a
+// line-relative threshold, not an absolute one.
+function isPunct(w) {
+    return /^[^A-Za-z0-9]+$/.test(w.lexicalClass) || w.syllables.length === 0;
+}
+/** Dependency depth of a word (number of governors up to the root). */
+function depthOf(w, memo) {
+    const seen = new Set();
+    let d = 0;
+    let cur = w;
+    while (cur) {
+        if (memo.has(cur)) {
+            d += memo.get(cur);
+            break;
+        }
+        if (seen.has(cur))
+            break; // cycle guard
+        seen.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        d++;
+        cur = g;
+    }
+    memo.set(w, d);
+    return d;
+}
+/** The syntactic head of a ϕ — the lowest-depth (closest to root) content token. */
+function phraseHead(tokens, memo) {
+    let best = null;
+    let bestD = Infinity;
+    for (const t of tokens) {
+        if (isPunct(t))
+            continue;
+        const d = depthOf(t, memo);
+        if (d < bestD) {
+            bestD = d;
+            best = t;
+        }
+    }
+    return best;
+}
+/** Lowest-common-ancestor depth of two words in the dependency tree. */
+function lcaDepth(a, b, memo) {
+    const anc = new Map();
+    let cur = a;
+    let d = 0;
+    const seen = new Set();
+    while (cur && !seen.has(cur)) {
+        anc.set(cur, d++);
+        seen.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        cur = g;
+    }
+    cur = b;
+    const seen2 = new Set();
+    while (cur && !seen2.has(cur)) {
+        if (anc.has(cur))
+            return depthOf(cur, memo);
+        seen2.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        cur = g;
+    }
+    return 0; // disjoint subtrees / different roots → treat as top-level (depth 0)
+}
+/** Is there a comma / dash / terminal punctuation token between A and B in surface
+ *  order, and is it a strong (ι-class) one? */
+function punctBetween(words, a, b) {
+    let comma = false, strong = false;
+    for (const w of words) {
+        if (w.absoluteIndex <= a.absoluteIndex || w.absoluteIndex >= b.absoluteIndex)
+            continue;
+        if (!isPunct(w))
+            continue;
+        if (w.word === ',' || w.lexicalClass === ',')
+            comma = true;
+        if (/^[.!?:;…]$/.test(w.word) || /^[.!?:;-]$/.test(w.lexicalClass) ||
+            w.lexicalClass === '-LRB-' || w.lexicalClass === '-RRB-')
+            strong = true;
+    }
+    return { comma, strong };
+}
+function sylCount(tokens) {
+    let n = 0;
+    for (const t of tokens)
+        n += t.syllables.length;
+    return n;
+}
+/** Flatten the ϕ of an ι into token lists. */
+function phiTokenLists(iu) {
+    return iu.phonologicalPhrases.map(pp => pp.cliticGroups.flatMap(cg => cg.tokens).filter(t => !isPunct(t)));
+}
+/**
+ * Compute graded boundary strength for every ϕ and ι boundary in a line.
+ */
+export function computeBoundaries(words, ius) {
+    const memo = new Map();
+    const maxDepth = Math.max(1, ...words.filter(w => !isPunct(w)).map(w => depthOf(w, memo)));
+    // Flatten ϕ across all ι in document order, remembering each ϕ's ι index.
+    const flatPhi = [];
+    ius.forEach((iu, iuIdx) => {
+        phiTokenLists(iu).forEach((tokens, ppIdx) => {
+            if (tokens.length)
+                flatPhi.push({ tokens, iuIdx, ppIdx });
+        });
+    });
+    let cumSyl = 0;
+    const phi = [];
+    const iota = [];
+    for (let k = 0; k < flatPhi.length; k++) {
+        const cur = flatPhi[k];
+        const prev = k > 0 ? flatPhi[k - 1] : null;
+        const isIotaBoundary = !!prev && cur.iuIdx !== prev.iuIdx;
+        let raw = 0;
+        if (prev) {
+            const aHead = phraseHead(prev.tokens, memo); // left phrase head
+            const bHead = phraseHead(cur.tokens, memo); // right phrase head
+            const aLast = prev.tokens[prev.tokens.length - 1];
+            const bFirst = cur.tokens[0];
+            // base rank by level
+            raw += isIotaBoundary ? 3.0 : 1.0;
+            // punctuation coincidence
+            const p = punctBetween(words, aLast, bFirst);
+            if (p.strong)
+                raw += 2.0;
+            else if (p.comma)
+                raw += 1.2;
+            // length of the preceding constituent (look-back): longer → stronger
+            raw += Math.min(1.5, sylCount(prev.tokens) / 6);
+            // clause separation: a shallow dependency LCA (near the root) → strong
+            if (aHead && bHead) {
+                const lca = lcaDepth(aHead, bHead, memo);
+                raw += 1.2 * (1 - Math.min(1, lca / maxDepth)); // shallow LCA → +clause bonus
+            }
+            // associative coordination weakening: same coordinator across the boundary
+            if (startsCoordinator(cur.tokens) && !p.comma && !p.strong)
+                raw -= 0.4;
+        }
+        const info = {
+            level: isIotaBoundary ? 'iota' : 'phi',
+            strength: 0, // filled after normalisation
+            raw: Math.max(0, raw),
+            syllableIndex: cumSyl,
+        };
+        phi.push(info);
+        if (isIotaBoundary)
+            iota.push(info);
+        cumSyl += sylCount(cur.tokens);
+    }
+    // NSBR normalisation: scale to the strongest boundary in the line (0..1).
+    const maxRaw = Math.max(0, ...phi.map(b => b.raw));
+    for (const b of phi)
+        b.strength = maxRaw > 0 ? b.raw / maxRaw : 0;
+    return { phi, iota };
+}
+function startsCoordinator(tokens) {
+    const t = tokens[0];
+    return !!t && (t.lexicalClass === 'CC' || t.canonicalRel === 'CC');
+}

package/dist/calliope/bracketing.d.ts

@@ -0,0 +1,11 @@
+import { ClsSentence, ClsWord } from '../types.js';
+/**
+ * Run the cyclic Compound + Nuclear Stress Rules (Wagner-extended) over the
+ * sentence's dependency tree and write each word's `phraseStress` (1 = strongest).
+ */
+export declare function computePhraseStress(sent: ClsSentence): void;
+/**
+ * Partition the sentence's words into ϕ-domains over the dependency tree.
+ */
+export declare function computePhiDomains(sent: ClsSentence): Map<ClsWord, number>;
+//# sourceMappingURL=bracketing.d.ts.map

package/dist/calliope/bracketing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bracketing.d.ts","sourceRoot":"","sources":["../../src/calliope/bracketing.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AA4HnD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAmF3D;AA4GD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CA6BzE"}