@llblab/pi-telegram 0.2.7 → 0.2.9

package/AGENTS.md

@@ -57,7 +57,8 @@
 - Keep comments and user-facing docs in English unless the surrounding file already follows another convention
 - Each project `.ts` file should start with a short multi-line responsibility header comment that explains the file boundary to future maintainers
 - Name extracted `/lib` modules and mirrored `/tests` suites by bare domain when the repository already supplies the Telegram scope; prefer `api.ts`, `queue.ts`, `updates.ts`, and `queue.test.ts` over redundant `telegram-*` filename prefixes
-- Prefer targeted edits, keeping `index.ts` as the orchestration layer and moving reusable logic into flat `/lib` domain modules when a subsystem becomes large enough to earn extraction; current extracted domains include queueing/runtime decisions, replies, polling, updates, attachments, registration and lifecycle-hook binding, Telegram API/config support, turn-building, media extraction, setup, rendering, status rendering, menu/model-resolution/UI support, and model-switch support
+- Prefer targeted edits, keeping `index.ts` as the orchestration layer and moving reusable logic into flat `/lib` domain modules when a subsystem becomes large enough to earn extraction; current extracted domains include queueing/runtime decisions, preview streaming, replies, polling, updates, attachments, registration and lifecycle-hook binding, Telegram API/config support, turn-building, media extraction, setup, rendering, status rendering, menu/model-resolution/UI support, and model-switch support
+- Keep preview appearance logic in the rendering domain and preview transport/lifecycle logic in the preview domain so richer streaming strategies can evolve without entangling Telegram delivery state with Markdown formatting rules
 
 ## 7. Operational Conventions
 

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Current
 
+- `[Rendering]` Hardened link rendering so absolute links stay clickable, markdown-heavy link labels reduce to plain clickable labels, tooltip titles are ignored safely, balanced-parenthesis URLs stay intact, and unsupported link forms degrade without broken anchors. Impact: Telegram replies now keep more links usable while avoiding malformed output for relative, reference-style, or footnote-like link syntax.
+- `[Preview]` Evolved rich streaming from first-chunk snapshots to stable-block previews with a conservative plain tail fallback, while preserving original blank-line spacing between rendered blocks and keeping headings visually separated from following blocks. Impact: closed top-level Markdown blocks now stream as rich Telegram HTML before finalization, incomplete fences, quotes, lists, and other trailing work remain readable without producing broken rich formatting, preview/final block spacing no longer collapses extra empty lines, and headings no longer visually merge into following code blocks when source Markdown omits a blank line.
+- `[Refactor]` Split preview concerns so runtime transport and finalization live in the preview domain while preview snapshot derivation lives in the rendering domain. Impact: rich streaming can evolve independently from final reply delivery while keeping preview appearance decisions closer to the Telegram renderer.
+- `[Streaming]` Switched Telegram previews from plain draft-first text to rich first-chunk message editing, so formatting appears during generation instead of only after finalization. Impact: users now see richer streamed output earlier, while final replies still replace the preview with fully rendered Telegram HTML.
+- `[Rendering]` Preserved leading indentation on the first Markdown line, kept numeric markers for ordered task lists in both preview and final Telegram rendering, and stopped reinterpreting standalone `[x]` or `[ ]` prose as inline checkboxes. Impact: nested content no longer flattens when a message starts with indentation, numbered checklists keep their ordered semantics, and literal checklist-like prose stays literal.
 - `[Queue UI]` Marked liked high-priority queued Telegram turns with `⬆` in the pi status-bar queue preview. Impact: operators can now distinguish reaction-promoted turns from normal queued prompts at a glance.
 - `[Docs]` Added short responsibility header comments to every project `.ts` file. Impact: file boundaries are easier to understand while navigating the growing `/lib` split.
 - `[Naming]` Renamed extracted domain modules and mirrored regression suites to use repo-scoped bare domain filenames such as `api.ts`, `queue.ts`, and `queue.test.ts` instead of repeating `telegram-*` in every path. Impact: the internal topology is easier to scan and stays aligned with the repository-level Telegram scope.

package/README.md

@@ -2,10 +2,9 @@
 
 ![pi-telegram screenshot](screenshot.png)
 
-Telegram DM bridge for pi.
+Better Telegram DM bridge for pi.
 
-This repository is a fork of the original [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram).
-It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
+This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
 ## Start Here
 
@@ -14,19 +13,15 @@ It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](htt
 - [Changelog](./CHANGELOG.md)
 - [Documentation](./docs/README.md)
 
-## What Changed In This Fork
+## Key Features
 
-Compared to upstream commit `cb34008`, this fork significantly extends and hardens the extension.
-
-- Better Telegram control UI, including an improved `/status` view with inline buttons for model and thinking selection
-- Interactive model selection improvements, including scoped model lists, thinking-level control for reasoning-capable models, and in-flight restart on a newly selected model for active Telegram-owned runs
-- Queueing and interaction upgrades, including queue previews, reaction-based prioritization/removal, media-group handling, high-priority control actions, and safer dispatch behavior
-- Markdown and reply rendering improvements, with richer formatting support, narrow-client-friendly table/list rendering, quote compatibility fixes, and multiple fixes for incorrect Telegram rendering and chunking edge cases
-- Streaming, attachment, and delivery workflow hardening, including more robust preview updates and file handling
-- General runtime polish, bug fixes, and refactors across pairing, command handling, and Telegram session behavior
-- Cleaner internal domain layout, with flat `/lib/*.ts` modules and mirrored `/tests/*.test.ts` suites that use repo-scoped domain names
-
-In short: this fork is no longer just a repackaged copy of upstream; it is a feature-expanded and bug-fixed Telegram frontend for pi.
+- **Priority Command Queue**: Control commands such as `/status` and `/model` use a high-priority control queue, so they do not get stuck behind normal queued prompts when pi is busy.
+- **Interactive UI**: Manage your session directly from Telegram. Inline buttons allow you to switch models and adjust reasoning (thinking) levels on the fly.
+- **In-flight Model Switching**: Change the active model mid-generation. The agent gracefully pauses, applies the new model, and restarts its response without losing context.
+- **Smart Message Queue**: Messages sent while the agent is busy are queued and previewed in the pi status bar, and queued turns can be reprioritized or removed with Telegram reactions.
+- **Mobile-Optimized Rendering**: Tables and lists are formatted for narrow screens. Markdown is correctly parsed and split to fit Telegram's limits without breaking HTML structures or code blocks, block spacing stays faithful to the original Markdown with readable heading separation, supported absolute links stay clickable, and unsupported link forms degrade safely.
+- **File Handling & Attachments**: Send images and files to the agent, or ask it to generate and return artifacts. Outbound files are delivered automatically via the `telegram_attach` tool.
+- **Streaming Responses**: Closed Markdown blocks stream back as rich Telegram HTML while pi is generating, and the still-growing tail stays readable until the final fully rendered reply lands.
 
 ## Install
 
@@ -42,22 +37,16 @@ From git:
 pi install git:github.com/llblab/pi-telegram
 ```
 
-Or for a single run:
-
-```bash
-pi -e @llblab/pi-telegram
-```
-
 ## Configure
 
-### Telegram
+### 1. Telegram Bot
 
 1. Open [@BotFather](https://t.me/BotFather)
 2. Run `/newbot`
 3. Pick a name and username
 4. Copy the bot token
 
-### pi
+### 2. Connect to pi
 
 Start pi, then run:
 
@@ -65,132 +54,59 @@ Start pi, then run:
 /telegram-setup
 ```
 
-Paste the bot token when prompted.
-If a bot token is already saved in `~/.pi/agent/telegram.json`, `/telegram-setup` shows that stored value by default. Otherwise it pre-fills from the first configured environment variable in `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`.
+Paste your bot token when prompted. If a bot token is already saved in `~/.pi/agent/telegram.json`, `/telegram-setup` shows that stored value by default. Otherwise it prefills from the first configured environment variable in `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`.
 
-The extension stores config in:
-
-```text
-~/.pi/agent/telegram.json
-```
-
-## Connect a pi session
-
-The Telegram bridge is session-local. Connect it only in the pi session that should own the bot:
+Link the bridge to your current pi session:
 
 ```bash
 /telegram-connect
 ```
 
-To stop polling in the current session:
-
-```bash
-/telegram-disconnect
-```
-
-Check status:
-
-```bash
-/telegram-status
-```
+_(Note: The bridge is session-local. Only one pi session can be connected to the bot at a time.)_
 
-## Pair your Telegram account
-
-After token setup and `/telegram-connect`:
+### 3. Pair your account
 
 1. Open the DM with your bot in Telegram
 2. Send `/start`
 
-The first DM user becomes the allowed Telegram user for the bridge. The extension only accepts messages from that user.
+The first user to message the bot becomes the exclusive owner of the bridge. The extension will only accept messages from this user.
 
 ## Usage
 
-Chat with your bot in Telegram DMs.
-
-Additional fork-specific controls:
-
-- `/status` now has a richer view with inline buttons for model and thinking controls, and joins the high-priority control queue when pi is busy
-- `/model` opens the interactive model selector, applies idle selections immediately, joins the high-priority control queue when pi is busy, and can restart the active Telegram-owned run on the newly selected model, waiting for the current tool call to finish when needed
-- `/compact` starts session compaction when pi and the Telegram queue are idle
-- Queue reactions: `👍` prioritizes a waiting turn, `👎` removes it
-
-### Send text
-
-Send any message in the bot DM. It is forwarded into pi with a `[telegram]` prefix.
+Once paired, simply chat with your bot in Telegram. All text, images, and files are forwarded to pi.
 
-### Send images and files
+### Commands & Controls
 
-Send images, albums, or files in the DM.
+- **`/status`**: View session stats, cost, and use inline buttons to change models.
+- **`/model`**: Open the interactive model selector.
+- **`/compact`**: Start session compaction (only works when the session is idle).
+- **`/stop`**: Abort the active run.
+- **`/telegram-disconnect`** (in pi): Stop polling in the current session.
+- **`/telegram-status`** (in pi): Check bridge status.
 
-The extension:
+### Queue, Reactions, and Media
 
-- downloads them to `~/.pi/agent/tmp/telegram`
-- includes local file paths in the prompt
-- forwards inbound images as image inputs to pi
+- If you send more Telegram messages while pi is busy, they are queued and processed in order.
+- `👍` moves a waiting turn into the priority block. Removing `👍` sends it back to its normal queue position, and adding `👍` again gives it a fresh priority position.
+- `👎` removes a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to the dislike reaction.
+- For media groups, a reaction on any message in the group applies to the whole queued turn.
+- Inbound images, albums, and files are downloaded to `~/.pi/agent/tmp/telegram`, local file paths are included in the prompt, and inbound images are forwarded to pi as image inputs.
+- Queue reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
 
-### Ask for files back
+### Requesting Files
 
-If you ask pi for a file or generated artifact, pi should call the `telegram_attach` tool. The extension then sends those files with the next Telegram reply.
+If you ask pi for a file or generated artifact (e.g., _"generate a shell script and attach it"_), pi will call the `telegram_attach` tool, and the extension will send the file alongside its next Telegram reply.
 
 Examples:
 
 - `summarize this image`
-- `read this README and summarize it`
-- `write me a markdown file with the plan and send it back`
 - `generate a shell script and attach it`
 
-### Stop a run
-
-In Telegram, send:
-
-```text
-stop
-```
-
-or:
-
-```text
-/stop
-```
-
-That aborts the active pi turn.
-
-### Queue follow-ups
-
-If you send more Telegram messages while pi is busy, they are queued and processed in order.
-
-The pi status bar shows queued Telegram turns as compact previews, for example:
-
-```text
-+3: [⬆ write a shell script…, summarize this image…, 📎 2 attachments]
-```
-
-Priority turns promoted with 👍 are marked with `⬆` in that queue preview.
-
-Each preview is limited to at most 4 words or 32 characters.
-
-### Reprioritize or discard queued messages
-
-While a message is still waiting in the queue:
-
-- React with 👍 to move it into the priority block
-- React with 👎 to remove it from the queue
-
-Priority is stable:
-
-- The first liked queued message stays ahead of later liked messages
-- Removing 👍 sends the message back to its normal queue position
-- Adding 👍 again gives it a fresh priority position
-
-For media groups, a reaction on any message in the group applies to the whole queued turn.
-
-Message reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
-
 ## Streaming
 
-The extension streams assistant text previews back to Telegram while pi is generating.
+The extension streams assistant previews back to Telegram while pi is generating.
 
-It tries Telegram draft streaming first with `sendMessageDraft`. If that is not supported for your bot, it falls back to `sendMessage` plus `editMessageText`.
+Rich previews are sent through editable messages because Telegram drafts are text-only. Closed top-level Markdown blocks can appear with formatting before the answer finishes, while the still-growing tail remains conservative and readable until the preview is replaced with the fully rendered Telegram HTML reply.
 
 ## Notes
 

package/docs/architecture.md

@@ -21,7 +21,9 @@ Current runtime areas include:
 
 - Telegram API types and local bridge state in `index.ts`
 - Queueing and queue-runtime helpers in `/lib/queue.ts`
-- Reply, preview, preview-finalization, reply-transport, and rendered-message delivery helpers in `/lib/replies.ts`
+- Preview transport-selection, preview-finalization, and preview-runtime helpers in `/lib/preview.ts`
+- Reply-transport and rendered-message delivery helpers in `/lib/replies.ts`
+- Preview appearance and snapshot derivation stay in `/lib/rendering.ts`, while `/lib/preview.ts` owns transport and lifecycle decisions, so richer preview strategies can evolve without entangling Markdown formatting with Telegram delivery state
 - Polling request, stop-condition, and long-poll loop helpers in `/lib/polling.ts`
 - Telegram API/config helpers and lazy bot-token client wrappers in `/lib/api.ts`
 - Telegram turn-building helpers in `/lib/turns.ts`
@@ -30,7 +32,7 @@ Current runtime areas include:
 - Telegram attachment queueing and delivery helpers in `/lib/attachments.ts`
 - Telegram tool, command, and lifecycle-hook registration helpers in `/lib/registration.ts`
 - Setup/token prompt helpers in `/lib/setup.ts`
-- Markdown and Telegram message rendering helpers in `/lib/rendering.ts`
+- Markdown, preview-snapshot, and Telegram message rendering helpers in `/lib/rendering.ts`
 - Status rendering helpers in `/lib/status.ts`
 - Menu/model-resolution, menu-state construction, pure menu-page derivation, pure menu render-payload builders, menu-message runtime, callback parsing, callback entry handling, callback mutation helpers, full model-callback planning and execution, interface-polished callback effect ports, status-thinking callback handling, and UI helpers in `/lib/menu.ts`
 - Model-switch guard, continuation, and restart helpers in `/lib/model-switch.ts`
@@ -94,12 +96,15 @@ Key rules:
 
 - Rich text should render cleanly in Telegram chats
 - Real code blocks must remain literal and escaped
+- Supported absolute HTTP(S) and mailto links should stay clickable, while unsupported link forms such as unresolved references, footnotes, or relative links without a known base should degrade safely instead of producing broken Telegram anchors
 - Markdown tables should keep their internal separators but drop the outer left and right borders when rendered as monospace blocks so narrow Telegram clients keep more usable width
 - Unordered Markdown lists should render with a monospace `-` marker and ordered Markdown lists should render with monospace numeric markers so list indentation stays more predictable on narrow Telegram clients
+- Real Markdown task-list items should render with checkbox markers, while standalone `[x]` and `[ ]` prose should stay literal instead of being reinterpreted as checklists
 - Nested Markdown quotes should flatten into one Telegram blockquote with added non-breaking-space indentation because Telegram does not render nested blockquotes reliably
+- Original blank-line spacing between Markdown blocks should stay intact in both preview and final rendering instead of being collapsed to one generic block separator, while headings should still keep readable separation from following blocks such as code fences even when source Markdown omits a blank line
 - Long replies must be split below Telegram's 4096-character limit
 - Chunking should avoid breaking HTML structure where possible
-- Preview rendering is intentionally simpler than final rich rendering
+- Preview rendering uses stable top-level Markdown blocks for rich Telegram HTML and appends the still-growing tail conservatively as readable plain text so the preview stays valid even when the answer is incomplete
 
 The renderer is a Telegram-specific formatter, not a general Markdown engine, so rendering changes should be treated as regression-prone.
 
@@ -109,10 +114,12 @@ During generation, the bridge streams previews back to Telegram.
 
 Preferred order:
 
-1. Try `sendMessageDraft`
-2. Fall back to `sendMessage` plus `editMessageText`
+1. Re-render the current Markdown buffer into a preview snapshot that renders closed top-level blocks as rich Telegram HTML and keeps the unstable tail conservative and readable
+2. Send or update that preview through `sendMessage` plus `editMessageText`, because `sendMessageDraft` is text-only for rich previews
 3. Replace the preview with the final rendered reply when generation ends
 
+Draft streaming can remain as a plain-text fallback path, but rich Telegram previews are driven through editable messages and stable-block snapshot selection.
+
 Outbound files are sent only after the active Telegram turn completes and must be staged through the `telegram_attach` tool.
 
 ## Interactive Controls
@@ -125,7 +132,7 @@ Current operator controls include:
 - Inline status buttons for model and thinking adjustments, applying idle selections immediately while still respecting busy-run restart rules
 - `/model` for interactive model selection, queued as a high-priority control item when needed and supporting in-flight restart of the active Telegram-owned run on a newly selected model
 - `/compact` for Telegram-triggered pi session compaction when the bridge is idle
-- Queue reactions using `👍` and `👎`
+- Queue reactions using `👍` and `👎`, with `👎` acting as the canonical queue-removal path because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
 
 ## In-Flight Model Switching
 

package/index.ts

@@ -87,11 +87,14 @@ import {
   type TelegramRenderMode,
 } from "./lib/rendering.ts";
 import {
-  buildTelegramReplyTransport,
   clearTelegramPreview,
   finalizeTelegramMarkdownPreview,
   finalizeTelegramPreview,
   flushTelegramPreview,
+  type TelegramPreviewRuntimeState,
+} from "./lib/preview.ts";
+import {
+  buildTelegramReplyTransport,
   sendTelegramMarkdownReply,
   sendTelegramPlainReply,
 } from "./lib/replies.ts";
@@ -235,14 +238,12 @@ interface TelegramMessageReactionUpdated {
 }
 
 interface TelegramUpdate {
-  _: string;
   update_id: number;
   message?: TelegramMessage;
   edited_message?: TelegramMessage;
   callback_query?: TelegramCallbackQuery;
   message_reaction?: TelegramMessageReactionUpdated;
   deleted_business_messages?: { message_ids?: unknown };
-  messages?: unknown;
 }
 
 interface TelegramGetFileResult {
@@ -269,14 +270,7 @@ interface DownloadedTelegramFile {
 
 type ActiveTelegramTurn = PendingTelegramTurn;
 
-interface TelegramPreviewState {
-  mode: "draft" | "message";
-  draftId?: number;
-  messageId?: number;
-  pendingText: string;
-  lastSentText: string;
-  flushTimer?: ReturnType<typeof setTimeout>;
-}
+type TelegramPreviewState = TelegramPreviewRuntimeState;
 
 interface TelegramMediaGroupState {
   messages: TelegramMessage[];
@@ -693,21 +687,28 @@ export default function (pi: ExtensionAPI) {
           text,
         });
       },
-      sendMessage: async (chatId: number, text: string) => {
+      sendMessage: async (
+        chatId: number,
+        text: string,
+        options?: { parseMode?: "HTML" },
+      ) => {
         return callTelegramApi<TelegramSentMessage>("sendMessage", {
           chat_id: chatId,
           text,
+          parse_mode: options?.parseMode,
         });
       },
       editMessageText: async (
         chatId: number,
         messageId: number,
         text: string,
+        options?: { parseMode?: "HTML" },
       ) => {
         await editTelegramMessageText({
           chat_id: chatId,
           message_id: messageId,
           text,
+          parse_mode: options?.parseMode,
         });
       },
       renderTelegramMessage,

package/lib/polling.ts

@@ -11,6 +11,8 @@ export interface TelegramUpdateLike {
   update_id: number;
 }
 
+// Standard Telegram DM polling does not expose ordinary message-deletion events,
+// so queue removal stays reaction-driven while delete-like business updates remain defensive-only.
 export const TELEGRAM_ALLOWED_UPDATES = [
   "message",
   "edited_message",

package/lib/preview.ts

@@ -0,0 +1,212 @@
+/**
+ * Telegram preview streaming helpers
+ * Owns preview transport selection, runtime updates, and preview finalization
+ */
+
+import {
+  buildTelegramPreviewSnapshot,
+  type TelegramPreviewRenderStrategy,
+  type TelegramPreviewSnapshot,
+  type TelegramRenderedChunk,
+  type TelegramRenderMode,
+} from "./rendering.ts";
+
+export interface TelegramPreviewStateLike {
+  mode: "draft" | "message";
+  draftId?: number;
+  messageId?: number;
+  pendingText: string;
+  lastSentText: string;
+  lastSentParseMode?: "HTML";
+  lastSentStrategy?: TelegramPreviewRenderStrategy;
+}
+
+export interface TelegramPreviewRuntimeState extends TelegramPreviewStateLike {
+  flushTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface TelegramSentPreviewMessageLike {
+  message_id: number;
+}
+
+export interface TelegramPreviewRuntimeDeps {
+  getState: () => TelegramPreviewRuntimeState | undefined;
+  setState: (state: TelegramPreviewRuntimeState | undefined) => void;
+  clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
+  maxMessageLength: number;
+  renderPreviewText: (markdown: string) => string;
+  getDraftSupport: () => "unknown" | "supported" | "unsupported";
+  setDraftSupport: (support: "unknown" | "supported" | "unsupported") => void;
+  allocateDraftId: () => number;
+  sendDraft: (chatId: number, draftId: number, text: string) => Promise<void>;
+  sendMessage: (
+    chatId: number,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<TelegramSentPreviewMessageLike>;
+  editMessageText: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<void>;
+  renderTelegramMessage: (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) => TelegramRenderedChunk[];
+  sendRenderedChunks: (
+    chatId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+  editRenderedMessage: (
+    chatId: number,
+    messageId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+}
+
+export function buildTelegramPreviewFinalText(
+  state: TelegramPreviewStateLike,
+): string | undefined {
+  const finalText = state.pendingText.trim();
+  if (finalText) return finalText;
+  if (
+    state.lastSentStrategy === "rich-stable-blocks" ||
+    state.lastSentParseMode === "HTML"
+  ) {
+    return undefined;
+  }
+  return state.lastSentText.trim() || undefined;
+}
+
+export function shouldUseTelegramDraftPreview(options: {
+  draftSupport: "unknown" | "supported" | "unsupported";
+  snapshot?: TelegramPreviewSnapshot;
+}): boolean {
+  return (
+    options.draftSupport !== "unsupported" &&
+    (options.snapshot === undefined || options.snapshot.strategy === "plain")
+  );
+}
+
+export async function clearTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  deps.clearScheduledFlush(state);
+  deps.setState(undefined);
+  if (state.mode !== "draft" || state.draftId === undefined) return;
+  try {
+    await deps.sendDraft(chatId, state.draftId, "");
+  } catch {
+    // ignore
+  }
+}
+
+export async function flushTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  state.flushTimer = undefined;
+  const snapshot = buildTelegramPreviewSnapshot({
+    state,
+    maxMessageLength: deps.maxMessageLength,
+    renderPreviewText: deps.renderPreviewText,
+    renderTelegramMessage: deps.renderTelegramMessage,
+  });
+  if (!snapshot) return;
+  if (
+    shouldUseTelegramDraftPreview({
+      draftSupport: deps.getDraftSupport(),
+      snapshot,
+    })
+  ) {
+    const draftId = state.draftId ?? deps.allocateDraftId();
+    state.draftId = draftId;
+    try {
+      await deps.sendDraft(chatId, draftId, snapshot.text);
+      deps.setDraftSupport("supported");
+      state.mode = "draft";
+      state.lastSentText = snapshot.text;
+      state.lastSentParseMode = snapshot.parseMode;
+      state.lastSentStrategy = snapshot.strategy;
+      return;
+    } catch {
+      deps.setDraftSupport("unsupported");
+    }
+  }
+  if (state.mode === "draft" && state.draftId !== undefined) {
+    try {
+      await deps.sendDraft(chatId, state.draftId, "");
+    } catch {
+      // ignore
+    }
+  }
+  if (state.messageId === undefined) {
+    const sent = await deps.sendMessage(chatId, snapshot.text, {
+      parseMode: snapshot.parseMode,
+    });
+    state.messageId = sent.message_id;
+    state.mode = "message";
+    state.lastSentText = snapshot.text;
+    state.lastSentParseMode = snapshot.parseMode;
+    state.lastSentStrategy = snapshot.strategy;
+    return;
+  }
+  await deps.editMessageText(chatId, state.messageId, snapshot.text, {
+    parseMode: snapshot.parseMode,
+  });
+  state.mode = "message";
+  state.lastSentText = snapshot.text;
+  state.lastSentParseMode = snapshot.parseMode;
+  state.lastSentStrategy = snapshot.strategy;
+}
+
+export async function finalizeTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const finalText = buildTelegramPreviewFinalText(state);
+  if (!finalText) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendMessage(chatId, finalText);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  deps.setState(undefined);
+  return state.messageId !== undefined;
+}
+
+export async function finalizeTelegramMarkdownPreview(
+  chatId: number,
+  markdown: string,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
+  if (chunks.length === 0) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendRenderedChunks(chatId, chunks);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  if (state.messageId === undefined) return false;
+  await deps.editRenderedMessage(chatId, state.messageId, chunks);
+  deps.setState(undefined);
+  return true;
+}