@pipedog/core 0.0.0 → 0.1.0

package/dist/utils/context/text_segment_map.d.ts

@@ -0,0 +1,611 @@
+export interface TextSegmentOptions {
+    /** The piece as a client displays it. */
+    original: string;
+    /**
+     * The same piece as it was sent to the TTS. Identical to `original` unless
+     * something rewrote it, and empty if it was dropped entirely.
+     */
+    tts: string;
+    /** Where the piece starts in the full original text. */
+    originalStart: number;
+    /**
+     * Where it ends. Cursors jump straight here once a rewritten piece is
+     * finished, since no position inside one means anything.
+     */
+    originalEnd: number;
+}
+/**
+ * A piece of the utterance, paired with what the TTS was given in its place.
+ *
+ * The map is a list of these, laid end to end over the whole utterance. In
+ * most of them the two sides are identical; the interesting ones are where a
+ * transform, a filter or a tag made them differ (see `isTransformed`).
+ *
+ * - `original`: the piece as a client displays it.
+ * - `tts`: the same piece as it was sent to the TTS. Identical to `original`
+ *   unless something rewrote it, and empty if it was dropped entirely.
+ * - `originalStart`: where the piece starts in the full original text.
+ * - `originalEnd`: where it ends. Cursors jump straight here once a rewritten
+ *   piece is finished, since no position inside one means anything.
+ */
+export declare class TextSegment {
+    readonly original: string;
+    readonly tts: string;
+    readonly originalStart: number;
+    readonly originalEnd: number;
+    constructor(options: TextSegmentOptions);
+    /**
+     * True when the two sides cannot be followed together, character by character.
+     *
+     * A segment like this is all or nothing. The cursors into the other texts
+     * wait at its start until every spoken word of it has arrived, then jump
+     * straight to its end, because no position inside it means anything.
+     *
+     * Any one of these makes it true:
+     *
+     * - the letters and digits differ, as in `"$42.50"` against
+     *   `"forty two dollars"`;
+     * - the two sides have different numbers of words;
+     * - the TTS side has tags in it, even when the words match. The cursor
+     *   through the spoken text has tag characters to cross that the other
+     *   texts do not have.
+     *
+     * Only the shape of a tag matters, never its name: `<phoneme
+     * ...>Siobhan</phoneme>` counts because of the tags around the word.
+     */
+    get isTransformed(): boolean;
+    /**
+     * How many letters and digits the spoken side of this segment has.
+     *
+     * This is what the provider's words spend as they arrive. On a rewritten
+     * segment it has nothing to do with `originalAlnumCount`: "forty two
+     * dollars" against "$42.50".
+     */
+    get ttsAlnumCount(): number;
+    /**
+     * How many letters and digits the original side of this segment has.
+     *
+     * This is what the cursors into `originalText` and `llmText` spend, since
+     * those texts hold the original characters, not the spoken ones.
+     */
+    get originalAlnumCount(): number;
+    toString(): string;
+}
+/**
+ * What happened when a word was offered to one segment.
+ *
+ * Trying one word against one segment is called a hop. Two of these answers
+ * end the attempt; the other two send the word on to the next segment.
+ *
+ * - `PLACED`: the word fits here. Move to the end of the match and stop.
+ * - `CROSSES`: this segment holds only the beginning of the word. Finish the
+ *   segment and take the rest of the word to the next one.
+ * - `EXHAUSTED`: there is nothing here that can be spoken, so no word will
+ *   ever match -- an empty side of the diff, or a lone `<break/>`. Finish the
+ *   segment and try the whole word again on the next one.
+ * - `NO_MATCH`: nothing here matches the word, usually a symbol the provider
+ *   reports differently from the text. Step every cursor past the next run of
+ *   punctuation, which the word stands for, and stop.
+ */
+export declare const _HopKind: {
+    readonly PLACED: 1;
+    readonly CROSSES: 2;
+    readonly EXHAUSTED: 3;
+    readonly NO_MATCH: 4;
+};
+export type _HopKind = (typeof _HopKind)[keyof typeof _HopKind];
+/**
+ * The outcome of offering one word to one segment.
+ *
+ * Produced by `TextSegmentMap._classifyHop`, collected by
+ * `TextSegmentMap._planHops`, and acted on by `TextSegmentMap._consumeWord`.
+ *
+ * - `kind`: which of the four outcomes happened.
+ * - `segmentAdvance`: how many characters to move forward in this segment.
+ *   The length of the match for `PLACED`, or a step past the next run of
+ *   punctuation for `NO_MATCH`. The other two leave it at 0 because they
+ *   finish the whole segment anyway.
+ * - `wordConsumed`: how many characters of the word this segment used up, and
+ *   so how many to drop before offering the rest to the next segment. Only
+ *   `CROSSES` sets it; `EXHAUSTED` passes the word on whole.
+ */
+export interface _Hop {
+    readonly kind: _HopKind;
+    readonly segmentAdvance: number;
+    readonly wordConsumed: number;
+}
+/**
+ * Answers "where are we?" in three versions of one utterance, word by word.
+ *
+ * A TTS provider reports the words it speaks. Each report has to be turned
+ * into a position -- but into a position in *three* different strings,
+ * because the same utterance exists in three forms at once:
+ *
+ * - `ttsText` -- what was actually spoken, tags and all:
+ *   `"Your balance is forty two dollars"`
+ * - `originalText` -- what a client displays: `"Your balance is $42.50"`
+ * - `llmText` -- what the LLM wrote, so what the transcript should keep:
+ *   `"Your balance is <b>$42.50</b>"`. Defaults to `originalText`.
+ *
+ * For a frame nothing rewrote, all three are the same string and every
+ * position is the same.
+ *
+ * **The hard part is that a spoken word need not appear in the other two.**
+ * The provider says `"dollars"`; nothing in `"$42.50"` matches it. So the map
+ * is built once, by diffing `ttsText` against `originalText` into aligned
+ * `TextSegment` pieces -- each either survived unchanged or was rewritten
+ * whole.
+ *
+ * `llmText` is never compared against the others, and does not need to be.
+ * It holds the same letters and digits as `originalText`, in the same order,
+ * and differs only in what is wrapped around them -- tags, delimiters,
+ * punctuation. So counting letters and digits is enough to keep it in step,
+ * and its cursor moves by that count.
+ *
+ * From then on one real cursor moves: `rawPos`, how far into `ttsText` the
+ * provider has got. `userFacingPos` and the two LLM cursors follow it:
+ *
+ * - Through an **unchanged** segment they keep pace, word for word.
+ * - Through a **rewritten** one they wait. There is no honest position
+ *   halfway through `"$42.50"` while `"forty two dollars"` is being spoken, so
+ *   they hold and then jump to the end of the span in one step when the last
+ *   of its words lands.
+ *
+ * The LLM side carries two of them because one position cannot answer both
+ * questions asked of it. `llmSpokenPos` is what the provider has reported;
+ * `llmPos` is what has been attributed to a word, and runs ahead of it over a
+ * mark stuck to a word the provider has already named. See
+ * `_advanceLlmCursors`.
+ *
+ * Callers ask two things. `wordBelongsCurrentSegment` -- does this token
+ * plausibly continue what is left to speak? -- and `advanceWord`, which
+ * consumes it. Both tolerate the ways providers mangle tokens (added
+ * punctuation, changed case or diacritics, a fragment of a half-open SSML
+ * tag) without the caller knowing anything about it; `_classifyHop` holds
+ * that logic.
+ *
+ * A word need not sit at the cursor to be placed. When the provider garbles
+ * or drops an event, the next good word still matches a few words on, and the
+ * text stepped over -- which no event will ever name -- is consumed with it.
+ * So the two questions above stay simple: a token either has a home somewhere
+ * in what is left to speak, or it belongs to another utterance entirely.
+ *
+ * @example
+ * // "$42.50" was sent to the TTS as "forty two dollars and fifty cents"
+ * const smap = new TextSegmentMap(
+ *   "Your balance is forty two dollars and fifty cents",
+ *   "Your balance is $42.50",
+ * );
+ * for (const word of ["Your", "balance", "is"]) {
+ *   smap.advanceWord(word); // unchanged: every cursor keeps pace
+ * }
+ * for (const word of ["forty", "two", "dollars", "and", "fifty"]) {
+ *   smap.advanceWord(word); // rewritten: the other two cursors wait
+ * }
+ * smap.advanceWord("cents"); // the span is done, so they jump to its end
+ * // smap.lastCompletedSegment.original === "$42.50"
+ * // smap.inTransformedSegment === false
+ */
+export declare class TextSegmentMap {
+    /** How many words a word may be placed past -- see `_lookaheadHop`. */
+    static readonly LOOKAHEAD_WORDS = 3;
+    protected _ttsText: string;
+    protected _originalText: string;
+    protected _llmText: string;
+    protected _segments: TextSegment[];
+    protected _segIdx: number;
+    protected _segRawPos: number;
+    protected _userFacingPos: number;
+    protected _llmPos: number;
+    protected _llmSpokenPos: number;
+    protected _lastCompleted: TextSegment | null;
+    protected _lastOverflow: string | null;
+    protected _lastLeadingDuplicate: number;
+    /**
+     * Line the three texts up against each other.
+     *
+     * The comparison happens once, here. Everything after this only moves
+     * cursors.
+     *
+     * @param ttsText What was sent to the TTS, and so what incoming words are
+     *   matched against. May carry synthesis tags and rewritten values.
+     * @param originalText The same content as a client displays it, before any
+     *   rewriting. Diffed against `ttsText` to build the segments.
+     * @param llmText The same content as the LLM wrote it, which may add
+     *   delimiters the other two never see. Rides its own cursor rather than
+     *   being diffed. Defaults to `originalText`.
+     */
+    constructor(ttsText: string, originalText: string, llmText?: string | null);
+    /**
+     * Compare the two texts and cut them into the segments the map walks.
+     *
+     * `difflib` lines them up a word at a time and reports each piece as equal,
+     * replaced, inserted or deleted. Every piece becomes one `TextSegment`.
+     * Spaces are kept as words of their own so that the positions stay exact.
+     *
+     * One extra step: a piece that came out equal is cut around any tag inside
+     * it, so a single tag does not turn the whole sentence into an
+     * all-or-nothing segment.
+     *
+     * Called once, from the constructor.
+     */
+    protected static _buildSegments(ttsText: string, originalText: string): TextSegment[];
+    protected _resetState(): void;
+    /**
+     * Return `word`, then with its last mark removed, then with every trailing
+     * mark removed.
+     *
+     * A TTS can add punctuation the text it was given never had -- reading a
+     * list item `"my account"` as a sentence and reporting `"account."`.
+     * Matching tries the word as it arrived first, then the trimmed forms.
+     *
+     * Dropping only the added mark comes before dropping them all, so the marks
+     * the text does have are still matched: `"images:."` lands past the colon
+     * in `"images:"`, and `"---."` keeps something to match at all. The
+     * variants are tried in order and empty ones are skipped.
+     */
+    protected static _wordVariants(word: string): string[];
+    /**
+     * Compare `remainingWord` to each candidate, character for character.
+     *
+     * Two things can match. If a candidate starts with the word, the word fits
+     * here (`PLACED`). If the word starts with a candidate, the candidate ran
+     * out first, so the rest of the word belongs to the next segment
+     * (`CROSSES`).
+     *
+     * `_foldedHop` calls this too, on folded copies of the same strings.
+     * Folding never changes a string's length, so a position found in a folded
+     * copy is the same position in the original.
+     *
+     * @param candidates `[text, offset]` pairs to match `remainingWord` against,
+     *   tried in order.
+     * @param remainingWord The word (or its trailing-punctuation-stripped
+     *   variant) to match.
+     * @param requireWordBoundary When true, the word must end where a word ends
+     *   in the candidate -- either it used the candidate up, or the next
+     *   character is not a letter or digit. This stops `"account"` from matching
+     *   the start of `"Accountant"`. Only the folded pass asks for it, because
+     *   folding away case makes that kind of accidental match much easier to hit.
+     * @returns A `PLACED` or `CROSSES` hop, or `null` if nothing matched.
+     */
+    protected static _literalHop(candidates: [string, number][], remainingWord: string, requireWordBoundary?: boolean): _Hop | null;
+    /**
+     * Count the characters at the start of `text` that are not letters or digits.
+     *
+     * For `", I can"` this returns 2 -- the comma and the space.
+     *
+     * With `stopAtMarkup`, counting also stops at a `'<'`, so the count never
+     * reaches inside a tag. Without it, `"<break/>hello"` would count past the
+     * `'<'`, and a provider that reports the tag's name `"break"` as a word
+     * would look like it had spoken it.
+     */
+    protected static _leadingNonalnumLen(text: string, stopAtMarkup?: boolean): number;
+    /**
+     * Return the three starting points a word may be matched against here.
+     *
+     * Providers disagree about what they include in a word, so the same text is
+     * offered from three places, each paired with how far in it starts:
+     *
+     * 1. The text as it is, for a provider that reports `" world"` with its own
+     *    leading space.
+     * 2. Past any spaces.
+     * 3. Past everything that is not a letter or digit, for a provider that
+     *    does not repeat punctuation it already spoke -- when `"I"` arrives for
+     *    `"Yeah, I can"`, the `", "` is still waiting here.
+     *
+     * Each start is further in than the last, so the closest match is tried
+     * first. Identical starting points are dropped.
+     */
+    protected static _matchCandidates(segmentRemaining: string): [string, number][];
+    /**
+     * Match `remainingWord` again, ignoring differences in how it is written.
+     *
+     * A provider may report a word in lower case, without accents, or with
+     * plain quotes: `"SQL"` as `"sql"`, `"café"` as `"cafe"`, `"don’t"` as
+     * `"don't"`. Folding both sides makes those the same.
+     *
+     * Folding swaps characters one for one and never adds or removes any, so
+     * the strings keep their length and a position found here means the same
+     * position in the original text.
+     *
+     * Because folding hides case, a short word could now match inside a longer
+     * one -- `"account"` inside `"Accountant"`. So a match here is only accepted
+     * if it ends where a word ends.
+     */
+    protected static _foldedHop(candidates: [string, number][], remainingWord: string): _Hop | null;
+    /**
+     * Match `remainingWord` again, with tags removed from both sides.
+     *
+     * A provider may report a word wrapped in tags the text it was given did
+     * not have, or the other way round. Removing tags from both sides lets the
+     * words themselves be compared.
+     *
+     * The match is found in text that has no tags, so its position has to be
+     * translated back to a position in the real text, tags included, by
+     * `rawOffsetAfterCleanChars`.
+     *
+     * Only `PLACED` comes out of this. A word that runs past the end of the
+     * segment is left to the two earlier passes.
+     */
+    protected static _markupHop(segmentRemaining: string, remainingWord: string): _Hop | null;
+    /**
+     * Look for `remainingWord` a few words further into this segment.
+     *
+     * Reached only once the three strategies above have all declined, which
+     * means the provider garbled or dropped an event and the text at the cursor
+     * will never be reported on its own. Matching a word a little further on
+     * puts the segment back in step, and the text stepped over is consumed with
+     * the word that found it rather than being lost.
+     *
+     * Two limits keep a coincidence from being read as a recovery. Only whole
+     * words anchor the match, so a partial prefix is not enough, and only the
+     * next `LOOKAHEAD_WORDS` of them are tried, so a word repeated later in a
+     * long segment cannot swallow everything before it.
+     *
+     * Word separators are what those anchors are found by, so a script written
+     * without them -- Japanese, Chinese -- offers a single word start for the
+     * whole run and never matches here; frames in one recover through
+     * force-complete instead. Spaced scripts, Korean among them, recover
+     * normally.
+     *
+     * `_foldedHop` alone does the matching, since it already demands the whole
+     * word this needs and folding only ever widens what matches -- the fold is
+     * one character for one, so anything matching literally matches folded too.
+     *
+     * A segment holding markup is left alone: tag names are made of letters, so
+     * a word start inside one would read as something spoken. That also keeps
+     * the match from anchoring inside a rewritten span whose words carry tags.
+     */
+    protected static _lookaheadHop(segmentRemaining: string, remainingWord: string): _Hop | null;
+    /**
+     * Decide what `remainingWord` does to the text left in this segment.
+     *
+     * Everything here is plain string comparison. No tag names are understood,
+     * and nothing is remembered between calls.
+     *
+     * Four ways of matching are tried, each more forgiving than the one before:
+     * `_literalHop`, then `_foldedHop`, then `_markupHop`. Any of them can
+     * report that the word fits here (`PLACED`) or that it runs past the end of
+     * the segment (`CROSSES`). Last comes `_lookaheadHop`, which places the word
+     * a few words further in, stepping over text a garbled or dropped event left
+     * unaccounted for.
+     *
+     * If none of them match, the answer depends on what is left in the segment:
+     *
+     * - `EXHAUSTED` when nothing here can be spoken -- only a tag such as
+     *   `<break/>`, or trailing spaces and punctuation. The segment is finished
+     *   so the word can try the next one. This is checked last, so a word that
+     *   really does match something like a trailing emoji is found by the
+     *   passes above first.
+     * - `NO_MATCH` otherwise. The word is taken to stand for the next run of
+     *   punctuation (see `_unmatchedSymbolLen`), so the cursors step past that
+     *   run alone, never past a letter or digit.
+     */
+    protected static _classifyHop(segmentRemaining: string, remainingWord: string): _Hop;
+    /**
+     * Count how far a word that matched nothing moves the cursor.
+     *
+     * Such a word is usually a symbol the provider reports differently from the
+     * text -- `"-"` for `"→"` -- so it stands for the next run of punctuation,
+     * and the cursor steps past that run alone:
+     *
+     *     " → step two"     -> 2, stops before " step"
+     *     " → ### **Title**" -> 2, stops before " ###"
+     *
+     * Stopping at whitespace is what matters: the symbols after it (`###`,
+     * `**`) arrive as events of their own, and stepping past them would leave
+     * those events nothing to match.
+     */
+    protected static _unmatchedSymbolLen(segmentRemaining: string): number;
+    /**
+     * Move every cursor to `newPos` within `seg`, and finish `seg` if reached.
+     *
+     * This is where the "keep pace or wait" rule from the class docstring is
+     * applied, and the only place the cursors into the other two texts move.
+     *
+     * **Unchanged segment** -- both sides hold the same text, so the other two
+     * cursors keep pace. They move by a count, not a position: however many
+     * letters and digits this step used up in the spoken text is how many they
+     * move past. `advanceByAlnums` does that, crossing tags for free (which is
+     * how a tag travels with the word beside it) and taking any punctuation
+     * stuck to the end of the word, so `"you?"` moves as one.
+     *
+     * **Rewritten segment** -- the other two cursors do not move at all until
+     * the segment is finished, then jump straight to its end.
+     *
+     * Either way a cursor stops before trailing spaces, which belong to
+     * whatever comes next.
+     */
+    protected _advanceCursorsTo(seg: TextSegment, newPos: number): void;
+    /**
+     * Move the cursors into the other two texts by what this step just spoke.
+     *
+     * The user-facing cursor moves by the count of letters and digits consumed
+     * here. The two LLM cursors have their own rule -- see `_advanceLlmCursors`.
+     */
+    protected _keepDerivedCursorsInPace(seg: TextSegment, newPos: number): void;
+    /**
+     * Move both LLM cursors for a step that just spoke `crossed`.
+     *
+     * The two answer different questions and so stop in different places,
+     * which is the whole reason there are two of them:
+     *
+     * - `llmSpokenPos` -- what has been **reported spoken**. It crosses exactly
+     *   the characters the raw cursor did, so it stops in front of a mark no
+     *   event has arrived for.
+     * - `llmPos` -- what has been **attributed**. It also takes a mark stuck to
+     *   the end of the word, since the conversation context is rebuilt by
+     *   joining the attributed spans and every character has to belong to one
+     *   of them: `"Yeah,"` then `"I"` reads back correctly where `"Yeah"` then
+     *   `", I"` would put a space before the comma.
+     *
+     * Attribution never moves backwards and never trails what was spoken, so a
+     * step that spends no budget on the attributed side -- an emoji, a symbol
+     * the source spells differently -- is still credited to the word that
+     * crossed it.
+     */
+    protected _advanceLlmCursors(crossed: string, nAlnum: number): void;
+    /** Jump the other two cursors to the end of `seg`, now that it is done. */
+    protected _commitTransformedSpan(seg: TextSegment): void;
+    /** Record `seg` as finished and move on to the next segment. */
+    protected _finishSegment(seg: TextSegment): void;
+    /**
+     * Work out what `word` would do, without moving anything.
+     *
+     * This decides; `_consumeWord` acts. Keeping them apart is what stops them
+     * disagreeing, since `_canConsumeWord` asks the same question and must get
+     * the same answer.
+     *
+     * Most words are placed by the first segment tried, and the walk stops
+     * there. It goes on when a segment cannot finish the job -- the word runs
+     * past it, or it has nothing speakable left -- and whatever remains of the
+     * word is offered to the next segment.
+     *
+     * @returns What each segment answered, in order, and whatever is left of
+     *   the word once the segments run out. Anything left over is the word
+     *   running past the end of this text.
+     */
+    protected _planHops(word: string): [_Hop[], string];
+    /**
+     * Move the cursors according to what `_planHops` decided.
+     *
+     * Anything left unplaced ran past the end of this text and is kept in
+     * `lastOverflow`, for the caller to hand to the next frame.
+     */
+    protected _consumeWord(word: string): void;
+    /**
+     * Take one spoken word and move every cursor to where it ends.
+     *
+     * Afterwards `lastCompletedSegment`, `lastOverflow` and
+     * `lastLeadingDuplicate` describe what this particular word did; each is
+     * cleared at the start of the next call.
+     *
+     * @param word One token from the provider's word-timestamp stream. It may
+     *   be a plain word, a word carrying its own spacing or punctuation, or a
+     *   fragment of a half-open tag -- matching is textual, so the caller does
+     *   not have to know which.
+     */
+    advanceWord(word: string): void;
+    /**
+     * Count characters at the start of `word` that were already spoken.
+     *
+     * In `"Yeah, I can"` the comma travels with `"Yeah"`. If the provider then
+     * reports the next word as `", I"` instead of `"I"`, the comma would be
+     * recorded twice, so this returns 2 -- the comma and its space.
+     *
+     * Returns 0 when that punctuation is new text instead (`'"hello'`), and
+     * when the word is nothing but punctuation, which is a mark arriving on its
+     * own. Must be called before the cursors move, while `llmPos` still sits at
+     * the end of the previous word.
+     */
+    protected _leadingDuplicateLen(word: string): number;
+    /**
+     * Return true if `word` could be the next thing spoken here.
+     *
+     * `advanceWord` without the moving, so a caller can check first. A false
+     * answer means the provider skipped ahead, and the word should go to the
+     * next frame instead.
+     *
+     * A word with no letters or digits gets a second chance from
+     * `_symbolBelongsHere`, since there is nothing in it to match on.
+     */
+    wordBelongsCurrentSegment(word: string): boolean;
+    /**
+     * Ask whether this word would be placed, without placing it.
+     *
+     * True if some segment would take the word, or if the word simply runs off
+     * the end. False if there are no segments left, or a segment turns it down.
+     */
+    protected _canConsumeWord(word: string): boolean;
+    /**
+     * Decide whether a word made only of punctuation or symbols belongs here.
+     *
+     * There is nothing in such a word to match on, so it gets two chances:
+     *
+     * 1. Look for the word itself in the text still to be spoken. The search
+     *    starts a little before the cursor, because punctuation is often taken
+     *    along with the word before it.
+     *
+     * 2. Accept it as a stand-in. Some providers report a different symbol than
+     *    the one they were given -- ElevenLabs reports `"->"` as `"-"` -- so the
+     *    first check can never succeed. If words remain to be spoken and the
+     *    next thing in the text is itself a symbol, treat the word as that
+     *    symbol.
+     */
+    protected _symbolBelongsHere(word: string): boolean;
+    /** How far into the user-facing text the spoken words have reached. */
+    get userFacingPos(): number;
+    /**
+     * How far into the LLM's text has been attributed to a word so far.
+     *
+     * Ahead of `llmSpokenPos` whenever a word swept up a mark that no event has
+     * reported yet; the text between the two is attributed but not yet spoken.
+     */
+    get llmPos(): number;
+    /**
+     * How far into the LLM's text the provider has actually reported speaking.
+     *
+     * What a caller showing progress, or ending a frame early, should read:
+     * text past this point has had no word event, so it still belongs to what
+     * is left to say even when `llmPos` has already credited it to a word.
+     */
+    get llmSpokenPos(): number;
+    /** How far into `ttsText` the provider has spoken, counted from its start. */
+    get rawPos(): number;
+    /**
+     * The end of the last word passed to `advanceWord`, if it did not fit.
+     *
+     * `null` most of the time. It is set only when that word ran past the end
+     * of `ttsText`, with no segment left to take the rest, which means the
+     * leftover belongs to the next frame. It is always the tail of the word
+     * that was passed in, so the part that did fit is
+     * `word.slice(0, word.length - lastOverflow.length)`.
+     */
+    get lastOverflow(): string | null;
+    /**
+     * How much of the last word's start was punctuation already spoken.
+     *
+     * The opposite end of the word from `lastOverflow`: that one is about a
+     * tail running past this text, this one about a head repeating punctuation
+     * the previous word already took. Cut both off to get the part of the word
+     * that belongs to this frame:
+     *
+     *     word.slice(lastLeadingDuplicate, word.length - (lastOverflow ?? "").length)
+     */
+    get lastLeadingDuplicate(): number;
+    /**
+     * True once every letter and digit in the text has been spoken.
+     *
+     * This is not the same as the cursor reaching the end. If all that is left
+     * is punctuation or tags, the text counts as finished even though those
+     * characters have not been walked over, because no word event is coming
+     * for them.
+     *
+     * There is one exception. Punctuation separated from its word by a space,
+     * as French writes `"Comment ça va ?"`, does arrive as its own word event,
+     * so the text stays unfinished until it does (see
+     * `_pendingSeparatedPunctuation`). Punctuation stuck to the word itself, as
+     * in `"you?"`, was already taken with the word.
+     */
+    get isComplete(): boolean;
+    /**
+     * True when all that is left is punctuation set off from its word by a space.
+     *
+     * Some languages write a space before a mark, as in `"va ?"` or
+     * `"Bonjour !"`. A TTS reports that mark as a word of its own, so the
+     * segment has to stay open until it arrives.
+     *
+     * Only real punctuation counts. A trailing emoji or arrow (`"day! 😊"`,
+     * `"→"`) never arrives as its own word, so it must not keep the segment
+     * open, and tags are removed first for the same reason. Only called once no
+     * letters or digits are left.
+     */
+    protected static _pendingSeparatedPunctuation(remaining: string): boolean;
+    /** True when the cursor is partway through a rewritten segment. */
+    get inTransformedSegment(): boolean;
+    /** The segment finished by the last `advanceWord` call, if any. */
+    get lastCompletedSegment(): TextSegment | null;
+    /** Put every cursor back to the start of the text. */
+    reset(): void;
+}
+//# sourceMappingURL=text_segment_map.d.ts.map