@oh-my-pi/pi-coding-agent 16.3.0 → 16.3.2

package/src/tts/speakable.ts

@@ -0,0 +1,382 @@
+/**
+ * Streaming markdown → speakable-segment transform for assistant speech.
+ *
+ * Sits between the assistant's raw streaming text deltas and the TTS engine,
+ * deciding both *what* is worth speaking and *when* a piece of text is ready
+ * to synthesize. Three passes:
+ *
+ * 1. Block pass (per character, stateful): drops fenced code blocks and table
+ *    rows, strips heading/bullet/blockquote markers (numbered-list markers are
+ *    spoken as "1, …"), and turns newlines into hard segment breaks.
+ * 2. Segmentation (stateful): emits a segment the moment a sentence boundary
+ *    appears — no next-sentence confirmation, which is what made the previous
+ *    engine-side splitter stall a full sentence behind generation. The first
+ *    segment cuts early at a clause boundary for fast time-to-first-audio, and
+ *    over-long unpunctuated runs are force-split so no segment exceeds the
+ *    synthesizer's input budget.
+ * 3. Inline normalization (per segment): markdown links speak their label,
+ *    bare URLs speak their host, inline-code ticks and emphasis markers are
+ *    stripped, multi-directory file paths collapse to their basename, HTML
+ *    tags are dropped, and whitespace is collapsed. Segments with no letters
+ *    or digits left are not spoken at all.
+ *
+ * Pure and synchronous — the vocalizer owns timers (idle flush) and the
+ * session lifecycle, so this class stays trivially unit-testable.
+ */
+
+/** Minimum length before the very first segment may cut at a sentence boundary. */
+const FIRST_SEGMENT_MIN = 12;
+/** Buffer length past which the first segment may cut at a clause boundary instead. */
+const FIRST_CLAUSE_MIN = 40;
+/** Hard cap for the first segment: force a word cut for fast time-to-first-audio. */
+const FIRST_FORCED_MAX = 140;
+/** Minimum segment length once speech has started (merges stubby sentences). */
+const MIN_SEGMENT = 24;
+/**
+ * Mid-stream soft cut: once this much unpunctuated text is buffered, split at
+ * a clause boundary instead of waiting for the sentence to end. Long sentences
+ * synthesize as clause-sized pieces, keeping the playback pipeline fed (a
+ * 280-char segment costs ~6s of synthesis — enough to drain the player dry).
+ */
+const SOFT_CLAUSE_LEN = 160;
+/**
+ * Hard cap per segment. Kokoro's `generate()` truncates past ~510 phoneme
+ * tokens rather than splitting, so every emission path must stay well under it.
+ */
+const MAX_SEGMENT = 280;
+
+/** Sentence-ending punctuation, optional closers, then whitespace. */
+const SENTENCE_BOUNDARY_RE = /[.!?…]+[)\]"'»”’]*\s/g;
+/** Clause punctuation followed by whitespace — early-cut and force-split points. */
+const CLAUSE_BOUNDARY_RE = /[,;:—–]\s/g;
+/** Abbreviations whose trailing dot is not a sentence boundary. */
+const ABBREVIATION_RE = /(?:^|\s)(?:e\.g|i\.e|etc|vs|Mr|Mrs|Ms|Dr|St|No)\.$/i;
+
+/** Line-start prefixes that may still grow into a block marker. */
+const UNDECIDED_PREFIX_RE = /^(?:#{1,6}|[-*+]|-{2,}|\*{2,}|_{2,}|\d{1,3}|\d{1,3}[.)]|>+|`{1,2}|~{1,2})$/;
+/** A whole line that is a horizontal rule (or setext underline) — silence. */
+const HR_LINE_RE = /^(?:-{3,}|\*{3,}|_{3,})\s*$/;
+
+const IMAGE_RE = /!\[([^\]]*)\]\(([^()]*)\)/g;
+const LINK_RE = /\[([^\]]+)\]\(([^()]*)\)/g;
+const AUTOLINK_RE = /<(https?:\/\/[^\s>]+)>/g;
+const BARE_URL_RE = /\bhttps?:\/\/[^\s<>()"'\]]+|\bwww\.[\w-]+(?:\.[\w-]+)+[^\s<>()"'\]]*/g;
+const INLINE_CODE_RE = /`{1,2}([^`]+)`{1,2}/g;
+const BOLD_STRIKE_RE = /\*\*|__|~~/g;
+const EMPHASIS_ASTERISK_RE = /\*(?=\S)|(?<=\S)\*/g;
+const EMPHASIS_UNDERSCORE_RE = /(^|\s)_+|_+(?=\s|$)/g;
+const HTML_TAG_RE = /<\/?[a-zA-Z][^<>]*>/g;
+const HR_INLINE_RE = /(^|\s)[-*_]{3,}(?=\s|$)/g;
+const PATH_RE = /(^|[\s("'`])((?:~|\.{1,2})?\/?[\w.@+-]+(?:\/[\w.@+-]+){2,}\/?)/g;
+const HAS_SPEAKABLE_RE = /[\p{L}\p{N}]/u;
+
+/** "https://github.com/foo/bar?x#y" → "github.com". */
+function speakableUrl(url: string): string {
+	return url
+		.replace(/^[a-z][\w+.-]*:\/\//i, "")
+		.replace(/^www\./i, "")
+		.replace(/[/?#].*$/, "");
+}
+
+/**
+ * Collapse one raw segment to its speakable form; empty string when nothing
+ * in it is worth vocalizing (pure markup, URLs-only, whitespace).
+ */
+function normalizeSpeakable(raw: string): string {
+	const spoken = raw
+		.replace(IMAGE_RE, "$1")
+		.replace(LINK_RE, "$1")
+		.replace(AUTOLINK_RE, (_match, url: string) => speakableUrl(url))
+		.replace(BARE_URL_RE, match => speakableUrl(match))
+		.replace(INLINE_CODE_RE, "$1")
+		.replace(BOLD_STRIKE_RE, "")
+		.replace(EMPHASIS_ASTERISK_RE, "")
+		.replace(EMPHASIS_UNDERSCORE_RE, "$1")
+		.replace(HTML_TAG_RE, " ")
+		.replace(HR_INLINE_RE, "$1")
+		.replace(PATH_RE, (_match, lead: string, path: string) => {
+			// "packages/coding-agent/src/tts/vocalizer.ts" → "vocalizer.ts".
+			const parts = path.split("/").filter(part => part.length > 0);
+			return lead + (parts[parts.length - 1] ?? path);
+		})
+		.replace(/\s+/g, " ")
+		.trim();
+	return HAS_SPEAKABLE_RE.test(spoken) ? spoken : "";
+}
+
+/**
+ * Earliest sentence boundary at or past `min` chars; -1 when none. Skips cuts
+ * that would strand an unclosed inline-code span or split an abbreviation.
+ */
+function findSentenceCut(text: string, min: number): number {
+	SENTENCE_BOUNDARY_RE.lastIndex = 0;
+	for (let match = SENTENCE_BOUNDARY_RE.exec(text); match; match = SENTENCE_BOUNDARY_RE.exec(text)) {
+		const cut = match.index + match[0].length;
+		if (cut < min) continue;
+		const head = text.slice(0, cut);
+		if (ABBREVIATION_RE.test(head.trimEnd())) continue;
+		if ((head.match(/`/g)?.length ?? 0) % 2 !== 0) continue;
+		return cut;
+	}
+	return -1;
+}
+
+/** Earliest clause boundary at or past `min` chars; -1 when none. */
+function findClauseCut(text: string, min: number): number {
+	CLAUSE_BOUNDARY_RE.lastIndex = 0;
+	for (let match = CLAUSE_BOUNDARY_RE.exec(text); match; match = CLAUSE_BOUNDARY_RE.exec(text)) {
+		const cut = match.index + match[0].length;
+		if (cut >= min) return cut;
+	}
+	return -1;
+}
+
+/**
+ * Latest clause boundary in `[min, max]` chars; -1 when none. Keeps soft-cut
+ * segments grouped near the target length instead of shaving off the earliest
+ * stale clause.
+ */
+function findLastClauseCut(text: string, min: number, max: number): number {
+	CLAUSE_BOUNDARY_RE.lastIndex = 0;
+	let best = -1;
+	for (let match = CLAUSE_BOUNDARY_RE.exec(text); match; match = CLAUSE_BOUNDARY_RE.exec(text)) {
+		const cut = match.index + match[0].length;
+		if (cut > max) break;
+		if (cut >= min) best = cut;
+	}
+	return best;
+}
+
+/** Word-level cut for text with no usable punctuation: last space at or before `max`. */
+function findForcedCut(text: string, max: number): number {
+	const space = text.lastIndexOf(" ", max);
+	return space > 0 ? space + 1 : Math.min(max, text.length);
+}
+
+/** How a line-start prefix resolved. */
+type PrefixDecision =
+	| { kind: "undecided" }
+	| { kind: "prose"; text: string }
+	| { kind: "marker"; spoken: string }
+	| { kind: "swallow" }
+	| { kind: "fence"; fence: string };
+
+function classifyPrefix(prefix: string): PrefixDecision {
+	if (prefix === "|") return { kind: "swallow" };
+	if (/^(?:`{3}|~{3})/.test(prefix)) return { kind: "fence", fence: prefix.slice(0, 3) };
+	if (/^#{1,6}[ \t]/.test(prefix)) return { kind: "marker", spoken: "" };
+	if (/^[-*+][ \t]/.test(prefix)) return { kind: "marker", spoken: "" };
+	const numbered = /^(\d{1,3})[.)][ \t]/.exec(prefix);
+	if (numbered) return { kind: "marker", spoken: `${numbered[1]}, ` };
+	if (/^>+/.test(prefix) && !/^>+$/.test(prefix)) {
+		return { kind: "prose", text: prefix.replace(/^>+[ \t]?/, "") };
+	}
+	if (UNDECIDED_PREFIX_RE.test(prefix)) return { kind: "undecided" };
+	return { kind: "prose", text: prefix };
+}
+
+/** Block-pass state: where the current character lands. */
+type BlockMode = "linestart" | "prose" | "swallow" | "code";
+
+/**
+ * One per utterance. Feed raw assistant deltas through {@link push}; each call
+ * returns the segments that became ready to speak. {@link flush} drains the
+ * remainder at message end; {@link flushIdle} drains it when generation stalls
+ * mid-sentence so speech doesn't sit on buffered text through a tool call.
+ */
+export class SpeakableStream {
+	#mode: BlockMode = "linestart";
+	/** Pending line-start characters while the block marker is still ambiguous. */
+	#prefix = "";
+	/** Opening fence of the code block being swallowed (``` or ~~~). */
+	#fence = "";
+	/** First characters of the current line inside a code block (fence-close probe). */
+	#codeLine = "";
+	/** Mode to enter after the current swallowed line ends (code for an opening fence). */
+	#afterSwallow: BlockMode = "linestart";
+	/** Prose accumulator the segmenter cuts from. */
+	#buf = "";
+	/** Whether anything has been emitted yet (enables the fast first segment). */
+	#spoke = false;
+
+	/** Consume a raw delta; returns segments now ready to speak, in order. */
+	push(delta: string): string[] {
+		const out: string[] = [];
+		for (const ch of delta) this.#consume(ch, out);
+		this.#extract(out);
+		return out;
+	}
+
+	/** Message end: drain everything left, including a trailing partial sentence. */
+	flush(): string[] {
+		const out: string[] = [];
+		if (this.#mode === "linestart" && this.#prefix.length > 0 && !HR_LINE_RE.test(this.#prefix)) {
+			this.#buf += this.#prefix;
+		}
+		this.#prefix = "";
+		this.#mode = "linestart";
+		this.#drain(out);
+		return out;
+	}
+
+	/**
+	 * Generation stalled (tool call, thinking block): speak what we have rather
+	 * than sit silent on buffered text. Keeps block state so the stream resumes
+	 * afterwards, and refuses stubby mid-sentence fragments — the buffer must be
+	 * a complete thought (trailing sentence punctuation) or at least
+	 * {@link MIN_SEGMENT} long, so a stall right after "The" stays silent
+	 * instead of turning into choppy one-word speech.
+	 */
+	flushIdle(): string[] {
+		const out: string[] = [];
+		const pending = this.#buf.trimEnd();
+		const completeThought = /[.!?…][)\]"'»”’]*$/.test(pending);
+		if (!completeThought && pending.length < MIN_SEGMENT) return out;
+		this.#drain(out);
+		return out;
+	}
+
+	#consume(ch: string, out: string[]): void {
+		switch (this.#mode) {
+			case "linestart":
+				this.#consumeLineStart(ch, out);
+				return;
+			case "prose":
+				if (ch === "\n") this.#hardBreak(out);
+				else this.#buf += ch;
+				return;
+			case "swallow":
+				if (ch === "\n") this.#mode = this.#afterSwallow;
+				return;
+			case "code":
+				this.#consumeCode(ch);
+				return;
+		}
+	}
+
+	#consumeLineStart(ch: string, out: string[]): void {
+		if (ch === "\n") {
+			// The whole line fit in the prefix: an hr/blank line is silence; a
+			// short undecided prefix ("Hi.", "OK") was prose all along.
+			const line = this.#prefix;
+			this.#prefix = "";
+			if (line.length > 0 && !HR_LINE_RE.test(line)) this.#buf += line;
+			this.#hardBreak(out);
+			return;
+		}
+		this.#prefix += ch;
+		const decision = classifyPrefix(this.#prefix);
+		if (decision.kind === "undecided") {
+			if (this.#prefix.length > 8) {
+				this.#buf += this.#prefix;
+				this.#prefix = "";
+				this.#mode = "prose";
+			}
+			return;
+		}
+		this.#prefix = "";
+		switch (decision.kind) {
+			case "prose":
+				this.#buf += decision.text;
+				this.#mode = "prose";
+				return;
+			case "marker":
+				this.#buf += decision.spoken;
+				this.#mode = "prose";
+				return;
+			case "swallow":
+				this.#mode = "swallow";
+				this.#afterSwallow = "linestart";
+				return;
+			case "fence":
+				this.#fence = decision.fence;
+				this.#codeLine = "";
+				this.#mode = "swallow";
+				this.#afterSwallow = "code";
+				return;
+		}
+	}
+
+	#consumeCode(ch: string): void {
+		if (ch === "\n") {
+			this.#codeLine = "";
+			return;
+		}
+		if (this.#codeLine.length < 3) {
+			this.#codeLine += ch;
+			if (this.#codeLine === this.#fence) {
+				// Closing fence: swallow the rest of its line, then resume prose.
+				this.#mode = "swallow";
+				this.#afterSwallow = "linestart";
+			}
+		}
+	}
+
+	/** Newline in prose: everything buffered is a complete unit — emit it now. */
+	#hardBreak(out: string[]): void {
+		this.#mode = "linestart";
+		this.#drain(out);
+	}
+
+	/** Emit every buffered character, force-splitting anything over the cap. */
+	#drain(out: string[]): void {
+		let text = this.#buf;
+		this.#buf = "";
+		while (text.length > MAX_SEGMENT) {
+			const cut = findForcedCut(text, MAX_SEGMENT);
+			this.#emit(text.slice(0, cut), out);
+			text = text.slice(cut);
+		}
+		this.#emit(text, out);
+	}
+
+	/** Cut ready segments off the front of the buffer (streaming path). */
+	#extract(out: string[]): void {
+		for (;;) {
+			const buf = this.#buf;
+			const min = this.#spoke ? MIN_SEGMENT : FIRST_SEGMENT_MIN;
+			const sentence = findSentenceCut(buf, min);
+			if (sentence !== -1) {
+				this.#cut(sentence, out);
+				continue;
+			}
+			if (!this.#spoke && buf.length >= FIRST_CLAUSE_MIN) {
+				const clause = findClauseCut(buf, FIRST_SEGMENT_MIN);
+				if (clause !== -1) {
+					this.#cut(clause, out);
+					continue;
+				}
+				if (buf.length >= FIRST_FORCED_MAX) {
+					this.#cut(findForcedCut(buf, FIRST_FORCED_MAX), out);
+					continue;
+				}
+			}
+			if (this.#spoke && buf.length >= SOFT_CLAUSE_LEN) {
+				const clause = findLastClauseCut(buf, MIN_SEGMENT, SOFT_CLAUSE_LEN);
+				if (clause !== -1) {
+					this.#cut(clause, out);
+					continue;
+				}
+			}
+			if (buf.length > MAX_SEGMENT) {
+				const clause = findLastClauseCut(buf, MIN_SEGMENT, MAX_SEGMENT);
+				this.#cut(clause !== -1 ? clause : findForcedCut(buf, MAX_SEGMENT), out);
+				continue;
+			}
+			return;
+		}
+	}
+
+	#cut(at: number, out: string[]): void {
+		const head = this.#buf.slice(0, at);
+		this.#buf = this.#buf.slice(at);
+		this.#emit(head, out);
+	}
+
+	#emit(raw: string, out: string[]): void {
+		const spoken = normalizeSpeakable(raw);
+		if (!spoken) return;
+		out.push(spoken);
+		this.#spoke = true;
+	}
+}

package/src/tts/speech-enhancer.ts

@@ -0,0 +1,204 @@
+/**
+ * Enhanced speech rewriting (`speech.enhanced`): turn assistant markdown into
+ * natural spoken prose with the tiny/smol model before synthesis.
+ *
+ * Two pieces:
+ * - {@link BlockAccumulator} — fence-aware paragraph splitter over the raw
+ *   streaming deltas. Blocks are blank-line-delimited; a fenced code block
+ *   never splits, and an idle-time {@link BlockAccumulator.flushPartial} while
+ *   inside a fence stays silent so half a code block is never sent to the
+ *   rewriter.
+ * - {@link SpeechEnhancer} — the per-session rewrite service the event
+ *   controller hands to the vocalizer. Resolves the tiny/smol role (same chain
+ *   as the auto-thinking classifier), sends one bounded completion per block,
+ *   and returns null on any failure or timeout so the caller falls back to the
+ *   mechanical {@link SpeakableStream} cleanup — speech never blocks on the
+ *   model.
+ */
+import { type AssistantMessage, completeSimple } from "@oh-my-pi/pi-ai";
+import { logger, prompt } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+import { getModelMatchPreferences, resolveModelRoleValue } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import speechRewritePrompt from "../prompts/system/speech-rewrite.md" with { type: "text" };
+
+const SYSTEM_PROMPT = prompt.render(speechRewritePrompt);
+/** Rewrite budget: a paragraph in, a spoken paragraph (usually shorter) out. */
+const ANSWER_MAX_TOKENS = 512;
+/** Reasoning backends may burn tokens before the answer despite `disableReasoning`. */
+const REASONING_SAFE_MAX_TOKENS = 1536;
+/** Per-block completion deadline before falling back to mechanical cleanup. */
+const REWRITE_TIMEOUT_MS = 6000;
+/** Bound block characters sent to the model (huge diffs/code dumps get elided). */
+const MAX_BLOCK_CHARS = 4000;
+
+/** Session-scoped dependencies; mirrors the auto-thinking classifier's deps. */
+export interface SpeechEnhancerDeps {
+	settings: Settings;
+	registry: ModelRegistry;
+	sessionId: string;
+	metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+}
+
+function extractText(content: AssistantMessage["content"]): string {
+	return content
+		.filter((block): block is Extract<AssistantMessage["content"][number], { type: "text" }> => block.type === "text")
+		.map(block => block.text)
+		.join(" ")
+		.trim();
+}
+
+/**
+ * Rewrites one markdown block into spoken prose via the tiny/smol role.
+ * Constructed per session by the event controller and handed to the vocalizer.
+ */
+export class SpeechEnhancer {
+	#deps: SpeechEnhancerDeps;
+
+	constructor(deps: SpeechEnhancerDeps) {
+		this.#deps = deps;
+	}
+
+	/**
+	 * Rewrite `block` for speech. Returns the spoken text (empty string when
+	 * the model judged the block unspeakable — pure code/markup), or null when
+	 * the rewrite failed, timed out, or no model/key resolved; the caller then
+	 * falls back to mechanical normalization.
+	 */
+	async rewrite(block: string, signal?: AbortSignal): Promise<string | null> {
+		try {
+			const { settings, registry, sessionId } = this.#deps;
+			// `pi/tiny` expands a configured `modelRoles.tiny` and otherwise falls
+			// through tiny's alias to the smol priority chain — unlike bare role
+			// lookup, this resolves even with no roles configured.
+			const model = resolveModelRoleValue("pi/tiny", registry.getAvailable(), {
+				settings,
+				matchPreferences: getModelMatchPreferences(settings),
+			}).model;
+			if (!model) return null;
+			const apiKey = await registry.getApiKey(model, sessionId);
+			if (!apiKey) return null;
+			// Resolve metadata after getApiKey so the session-sticky credential is recorded first.
+			const metadata = this.#deps.metadataResolver?.(model.provider);
+			const timeout = AbortSignal.timeout(REWRITE_TIMEOUT_MS);
+			const response = await completeSimple(
+				model,
+				{
+					systemPrompt: [SYSTEM_PROMPT],
+					messages: [{ role: "user", content: boundBlock(block), timestamp: Date.now() }],
+				},
+				{
+					apiKey: registry.resolver(model, sessionId),
+					maxTokens: model.reasoning ? REASONING_SAFE_MAX_TOKENS : ANSWER_MAX_TOKENS,
+					disableReasoning: true,
+					metadata,
+					signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+				},
+			);
+			if (response.stopReason === "error") {
+				logger.debug("speech-enhancer: rewrite errored", { error: response.errorMessage });
+				return null;
+			}
+			return extractText(response.content);
+		} catch (error) {
+			if (!signal?.aborted) {
+				logger.debug("speech-enhancer: rewrite failed", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+			return null;
+		}
+	}
+}
+
+/** Elide the middle of an oversized block so the prompt stays bounded. */
+function boundBlock(block: string): string {
+	if (block.length <= MAX_BLOCK_CHARS) return block;
+	const half = MAX_BLOCK_CHARS / 2;
+	return `${block.slice(0, half)}\n… (elided) …\n${block.slice(-half)}`;
+}
+
+/**
+ * Fence-aware paragraph accumulator over raw streaming deltas. One instance
+ * per utterance.
+ */
+export class BlockAccumulator {
+	/** Complete lines of the block being accumulated. */
+	#lines: string[] = [];
+	/** Trailing characters of the current, still-incomplete line. */
+	#partial = "";
+	/** Opening fence chars while inside a code block, else null. */
+	#fence: string | null = null;
+	/** Index into {@link #lines} where the open fence started (drop point for a truncated fence). */
+	#fenceStart = 0;
+
+	/** Feed a delta; returns the blocks it completed, in order. */
+	push(delta: string): string[] {
+		const out: string[] = [];
+		let text = this.#partial + delta;
+		for (;;) {
+			const nl = text.indexOf("\n");
+			if (nl === -1) break;
+			const line = text.slice(0, nl);
+			text = text.slice(nl + 1);
+			this.#consumeLine(line, out);
+		}
+		this.#partial = text;
+		return out;
+	}
+
+	/**
+	 * Message end: drain everything. An unterminated code fence is dropped from
+	 * its opening line onward (a truncated block is never worth speaking); the
+	 * prose before it still comes out.
+	 */
+	flush(): string | null {
+		if (this.#partial.length > 0) {
+			this.#lines.push(this.#partial);
+			this.#partial = "";
+		}
+		if (this.#fence !== null) {
+			this.#lines.length = this.#fenceStart;
+			this.#fence = null;
+		}
+		return this.#take();
+	}
+
+	/**
+	 * Generation stalled: drain the pending partial block — unless we are
+	 * inside a code fence, where the only thing buffered is code and speaking
+	 * or rewriting half a fence would re-introduce vocalized code. Fence state
+	 * is preserved so the eventual closing fence still matches.
+	 */
+	flushPartial(): string | null {
+		if (this.#fence !== null) return null;
+		if (this.#partial.length > 0) {
+			this.#lines.push(this.#partial);
+			this.#partial = "";
+		}
+		return this.#take();
+	}
+
+	#consumeLine(line: string, out: string[]): void {
+		const fence = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+		if (this.#fence === null && fence !== undefined) {
+			this.#fence = fence.slice(0, 3);
+			this.#fenceStart = this.#lines.length;
+		} else if (this.#fence !== null && fence?.startsWith(this.#fence)) {
+			this.#fence = null;
+		}
+		if (this.#fence === null && fence === undefined && line.trim().length === 0) {
+			const block = this.#take();
+			if (block !== null) out.push(block);
+			return;
+		}
+		this.#lines.push(line);
+	}
+
+	#take(): string | null {
+		if (this.#lines.length === 0) return null;
+		const block = this.#lines.join("\n");
+		this.#lines = [];
+		return block;
+	}
+}