@yaebal/rich 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @yaebal/rich
+
+`sendRichMessage` / `sendRichMessageDraft` — telegram's block-tree message format. a typed builder for the extended html dialect, a draft/streaming session that owns the 30s ttl, and full read-side coverage (type guards + plain-text flattening) of everything telegram can hand back on `message.rich_message`.
+
+unlike classic `parse_mode`/entities (see [`@yaebal/fmt`](https://www.npmjs.com/package/@yaebal/fmt)), a rich message isn't a flat `{ text, entities }` pair — it's a document: paragraphs, headings, tables, lists, collages, slideshows, block quotes, a collapsible `<details>`, even a `<tg-thinking>` placeholder for streaming an in-progress answer. you write extended html (or markdown), telegram parses it server-side into a `RichMessage.blocks` tree, and that same tree is what you read back.
+
+## install
+
+```sh
+pnpm add @yaebal/rich
+```
+
+## sending
+
+```ts
+import { document, heading, paragraph, bold, link, sendRichMessage } from "@yaebal/rich";
+
+const input = document([
+  heading(1, "release notes"),
+  paragraph("yaebal ", bold("0.1"), " is out — see ", link("https://yaeb.al", "the docs"), "."),
+]);
+
+await sendRichMessage(ctx.api, ctx.chat.id, input);
+```
+
+or install the plugin for `ctx.send`-flavored ergonomics:
+
+```ts
+import { Bot } from "@yaebal/core";
+import { rich, document, paragraph } from "@yaebal/rich";
+
+const bot = new Bot(token)
+  .install(rich())
+  .command("hi", (ctx) => ctx.sendRichMessage(document([paragraph("hello!")])));
+```
+
+## streaming a draft
+
+`sendRichMessageDraft` streams a partial answer to a private chat — but the draft is **ephemeral**: telegram drops it 30 seconds after the last push, and it never becomes a real message on its own. `RichMessageDraft` owns that lifecycle: it re-pushes the latest draft on a timer so a slow generator doesn't lose it, and it refuses to push after you close it.
+
+```ts
+import { thinking, document, paragraph, sendRichMessage } from "@yaebal/rich";
+
+bot.command("ask", async (ctx) => {
+  const draft = ctx.richMessageDraft(1); // draft_id, non-zero, per-message
+
+  await draft.push(thinking("thinking…")); // draft-only block, see below
+
+  let text = "";
+  for await (const chunk of streamAnswer(ctx.text)) {
+    text += chunk;
+    await draft.push(document([paragraph(text)]));
+  }
+
+  // required: a draft never persists on its own.
+  await draft.commit(document([paragraph(text)]));
+});
+```
+
+call `draft.cancel()` instead of `commit()` to abandon a draft without persisting anything (it expires within 30s regardless).
+
+## reading
+
+```ts
+import { richMessageToPlainText, isTable, isPhoto } from "@yaebal/rich";
+
+bot.on("message:rich_message", (ctx) => {
+  const plain = richMessageToPlainText(ctx.message.rich_message);
+  const tables = ctx.message.rich_message.blocks.filter(isTable);
+});
+```
+
+`richMessageToPlainText` / `richBlockToPlainText` / `richTextToPlainText` flatten the whole tree (or one node) to plain characters — useful for search indices, logs, or notification previews. every `RichBlock`/`RichText` variant has a matching `isX` type guard (`isParagraph`, `isTable`, `isCustomEmoji`, `isDateTime`, …).
+
+## coverage
+
+every one of telegram's ~50 `Rich*` types is covered on both sides:
+
+- **write** — a builder function (or documented auto-detection) for every block and inline mark.
+- **read** — an `isX` type guard and a plain-text flattening branch for every block and inline mark.
+
+most tags are **confirmed** directly from telegram's schema (`<p>`, `<h1>`–`<h6>`, `<pre><code>`, `<hr/>`, `<footer>`, `<blockquote>`, `<aside>` for pull-quotes, `<details>`/`<summary>`, `<table>`, `<tg-collage>`, `<tg-slideshow>`, `<tg-map>`, `<tg-math-block>`, `<tg-thinking>`, `<img>`/`<video>`/`<audio>`, `<a name>`/`<a href="#…">`, `<cite>`, and the classic `<b>`/`<i>`/`<u>`/`<s>`/`<code>`/`<tg-spoiler>`/`<tg-emoji>`/`tg://user?id=…` set). `url`/`email_address`/`phone_number`/`bank_card_number`/`@mention`/`#hashtag`/`$cashtag`/`/bot_command` need **no explicit tag at all** — telegram auto-detects them from plain text unless you pass `skipEntityDetection: true`.
+
+a handful of inline/block features have **no documented tag** in the schema at all (`marked`, `subscript`, `superscript`, `date_time`, inline `mathematical_expression`, `reference`/`reference_link`, table `is_bordered`/`is_striped`). those are implemented as a best-effort guess (standard html5 tags where one exists, a `tg-*`-style name otherwise) and flagged in their doc comments in `inline.ts`/`blocks.ts` — verify against the live "rich message formatting options" docs before relying on the exact spelling in production.
+
+`sendRichMessage` has no `attach://`/multipart upload path (unlike `sendPhoto`) — media blocks (`image`/`video`/`audio`) take a hosted url, not a local file.
+
+## api
+
+| export                                                                                                 | what                                                                      |
+|:-------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
+| `html`                                                                                                 | tagged template for the extended-html dialect, auto-escaped interpolation |
+| `bold`/`italic`/`underline`/`strikethrough`/`spoiler`/`code`/`marked`/`subscript`/`superscript`        | inline marks                                                              |
+| `link`/`textMention`/`anchor`/`anchorLink`/`customEmoji`/`dateTime`/`math`/`reference`/`referenceLink` | inline nodes with data                                                    |
+| `paragraph`/`heading`/`preformatted`/`footer`/`divider`/`mathBlock`/`anchorBlock`                      | simple blocks                                                             |
+| `blockquote`/`pullquote`/`details`/`list`/`item`/`table`/`cell`                                        | structural blocks                                                         |
+| `collage`/`slideshow`/`map`/`image`/`video`/`audio`/`thinking`                                         | media & draft-only blocks                                                 |
+| `document`/`markdown`                                                                                  | assemble blocks into an `InputRichMessage`                                |
+| `sendRichMessage`/`sendRichMessageDraft`                                                               | standalone send functions, no plugin required                             |
+| `rich()`                                                                                               | plugin: adds `ctx.sendRichMessage`/`ctx.richMessageDraft`                 |
+| `RichMessageDraft`                                                                                     | the draft/streaming session class                                         |
+| `isParagraph`, `isTable`, `isCustomEmoji`, …                                                           | one type guard per `RichBlock`/`RichText` variant                         |
+| `richTextToPlainText`/`richBlockToPlainText`/`richMessageToPlainText`                                  | flatten to plain text                                                     |
+
+plus the full generated type surface (`RichMessage`, `RichBlock`, `RichText`, and every `RichBlock*`/`RichText*` interface) re-exported from `@yaebal/types` for convenience.
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/blocks.d.ts

@@ -0,0 +1,115 @@
+import { type Insertable, type RichNode } from "./inline.js";
+/** a caption + optional credit for a media/collage/slideshow/map block (`RichBlockCaption`). */
+export interface Caption {
+    caption?: Insertable;
+    /** `RichBlockCaption.credit`, confirmed `<cite>`. */
+    credit?: Insertable;
+}
+/** `RichBlockParagraph`, `<p>`. */
+export declare function paragraph(...children: Insertable[]): RichNode;
+/** `RichBlockSectionHeading`, `<h1>`–`<h6>`. `level` is telegram's `size` (1 largest, 6 smallest). */
+export declare function heading(level: 1 | 2 | 3 | 4 | 5 | 6, ...children: Insertable[]): RichNode;
+/** `RichBlockPreformatted`, nested `<pre><code>`, matching classic parse_mode html. */
+export declare function preformatted(text: string, language?: string): RichNode;
+/** `RichBlockFooter`, `<footer>`. */
+export declare function footer(...children: Insertable[]): RichNode;
+/** `RichBlockDivider`, `<hr/>`. */
+export declare function divider(): RichNode;
+/** `RichBlockMathematicalExpression`, confirmed `<tg-math-block>` (LaTeX). */
+export declare function mathBlock(expression: string): RichNode;
+/** `RichBlockAnchor`, `<a name="…">` at block level. */
+export declare function anchorBlock(name: string): RichNode;
+/** `RichBlockBlockQuotation`, `<blockquote>`, with an optional `<cite>` credit. */
+export declare function blockquote(children: Insertable[], credit?: Insertable): RichNode;
+/** `RichBlockPullQuotation`, loosely `<aside>` per the schema, with an optional `<cite>` credit. */
+export declare function pullquote(text: Insertable, credit?: Insertable): RichNode;
+/** `RichBlockCollage`, confirmed custom tag `<tg-collage>`. */
+export declare function collage(blocks: Insertable[], caption?: Caption): RichNode;
+/** `RichBlockSlideshow`, confirmed custom tag `<tg-slideshow>`. */
+export declare function slideshow(blocks: Insertable[], caption?: Caption): RichNode;
+export interface TableCellOptions {
+    header?: boolean;
+    colspan?: number;
+    rowspan?: number;
+    /** default `"left"`, matching `RichBlockTableCell.align`. */
+    align?: "left" | "center" | "right";
+    /** default `"top"`, matching `RichBlockTableCell.valign`. */
+    valign?: "top" | "middle" | "bottom";
+}
+/** one `<td>`/`<th>` cell; `content` omitted ⇒ an invisible cell (per `RichBlockTableCell`). */
+export declare function cell(content?: Insertable, options?: TableCellOptions): RichNode;
+export interface TableOptions {
+    /** best-effort: rendered as the `border` attribute. */
+    bordered?: boolean;
+    /** best-effort: no standard html equivalent, rendered as `data-striped`. */
+    striped?: boolean;
+    caption?: Insertable;
+}
+/** `RichBlockTable`, confirmed `<table>`. build rows with `cell()`. */
+export declare function table(rows: Insertable[][], options?: TableOptions): RichNode;
+export interface DetailsOptions {
+    /** `RichBlockDetails.is_open` — content visible by default. defaults to `false`. */
+    open?: boolean;
+}
+/** `RichBlockDetails`, confirmed `<details>`/`<summary>`. */
+export declare function details(summary: Insertable, blocks: Insertable[], options?: DetailsOptions): RichNode;
+export interface ListItemOptions {
+    /** an unchecked/checked checkbox prefix (`RichBlockListItem.has_checkbox`/`is_checked`). */
+    checkbox?: boolean;
+    checked?: boolean;
+    /** ordered-list numeric override (`RichBlockListItem.value`) — standard `<li value>`. */
+    value?: number;
+    /** ordered-list label style override (`RichBlockListItem.type`) — standard `<li type>`. */
+    type?: "a" | "A" | "i" | "I";
+}
+/** one `<li>` for `list()`. */
+export declare function item(blocks: Insertable[], options?: ListItemOptions): RichNode;
+export interface ListOptions {
+    /** `<ol>` instead of `<ul>`. defaults to `false`. */
+    ordered?: boolean;
+}
+/** `RichBlockList`, `<ul>`/`<ol>` of `item()`s. */
+export declare function list(items: Insertable[], options?: ListOptions): RichNode;
+export interface MapOptions {
+    /** 13–20, per `RichBlockMap.zoom`. */
+    zoom: number;
+    width: number;
+    height: number;
+}
+/**
+ * `RichBlockMap`, confirmed custom tag `<tg-map>` — attribute names/encoding are a
+ * best-effort guess (lat/long/zoom/width/height are telegram's own field names).
+ */
+export declare function map(location: {
+    latitude: number;
+    longitude: number;
+}, options: MapOptions, caption?: Caption): RichNode;
+export interface MediaOptions extends Caption {
+    /** cover the media with a spoiler animation until tapped. */
+    spoiler?: boolean;
+}
+/**
+ * `RichBlockPhoto`, confirmed `<img>`. media is referenced by url — `sendRichMessage`
+ * has no multipart/`attach://` upload path (unlike `sendPhoto`), so there is no
+ * `MediaSource` overload here; host the file and pass its url.
+ */
+export declare function image(src: string, options?: MediaOptions): RichNode;
+/**
+ * `RichBlockVideo` **and** `RichBlockAnimation` both map to `<video>` per the
+ * schema (telegram tells the two apart server-side, e.g. by looping/silence —
+ * not by tag). there is no separate `animation()` builder for that reason.
+ */
+export declare function video(src: string, options?: MediaOptions): RichNode;
+/**
+ * `RichBlockAudio` **and** `RichBlockVoiceNote` both map to `<audio>` per the
+ * schema (again disambiguated server-side, not by tag) — there is no separate
+ * `voiceNote()` builder for that reason.
+ */
+export declare function audio(src: string, options?: MediaOptions): RichNode;
+/**
+ * `RichBlockThinking`, confirmed custom tag `<tg-thinking>`. **draft-only** — the
+ * schema states it can be used in `sendRichMessageDraft` payloads but is never
+ * received back on a real message. see `RichMessageDraft` in draft.ts.
+ */
+export declare function thinking(...children: Insertable[]): RichNode;
+//# sourceMappingURL=blocks.d.ts.map

package/lib/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}

package/lib/blocks.js

@@ -0,0 +1,149 @@
+import { escapeAttr, escapeText } from "./escape.js";
+import { toHtml } from "./inline.js";
+function join(children) {
+    return children.map(toHtml).join("");
+}
+function figcaption({ caption, credit }) {
+    if (caption === undefined && credit === undefined)
+        return "";
+    const creditHtml = credit === undefined ? "" : `<cite>${toHtml(credit)}</cite>`;
+    return `<figcaption>${toHtml(caption)}${creditHtml}</figcaption>`;
+}
+// --- confirmed tags ---
+/** `RichBlockParagraph`, `<p>`. */
+export function paragraph(...children) {
+    return { html: `<p>${join(children)}</p>` };
+}
+/** `RichBlockSectionHeading`, `<h1>`–`<h6>`. `level` is telegram's `size` (1 largest, 6 smallest). */
+export function heading(level, ...children) {
+    return { html: `<h${level}>${join(children)}</h${level}>` };
+}
+/** `RichBlockPreformatted`, nested `<pre><code>`, matching classic parse_mode html. */
+export function preformatted(text, language) {
+    const cls = language ? ` class="language-${escapeAttr(language)}"` : "";
+    return { html: `<pre><code${cls}>${escapeText(text)}</code></pre>` };
+}
+/** `RichBlockFooter`, `<footer>`. */
+export function footer(...children) {
+    return { html: `<footer>${join(children)}</footer>` };
+}
+/** `RichBlockDivider`, `<hr/>`. */
+export function divider() {
+    return { html: "<hr/>" };
+}
+/** `RichBlockMathematicalExpression`, confirmed `<tg-math-block>` (LaTeX). */
+export function mathBlock(expression) {
+    return { html: `<tg-math-block>${escapeText(expression)}</tg-math-block>` };
+}
+/** `RichBlockAnchor`, `<a name="…">` at block level. */
+export function anchorBlock(name) {
+    return { html: `<a name="${escapeAttr(name)}"></a>` };
+}
+/** `RichBlockBlockQuotation`, `<blockquote>`, with an optional `<cite>` credit. */
+export function blockquote(children, credit) {
+    const creditHtml = credit === undefined ? "" : `<cite>${toHtml(credit)}</cite>`;
+    return { html: `<blockquote>${join(children)}${creditHtml}</blockquote>` };
+}
+/** `RichBlockPullQuotation`, loosely `<aside>` per the schema, with an optional `<cite>` credit. */
+export function pullquote(text, credit) {
+    const creditHtml = credit === undefined ? "" : `<cite>${toHtml(credit)}</cite>`;
+    return { html: `<aside>${toHtml(text)}${creditHtml}</aside>` };
+}
+/** `RichBlockCollage`, confirmed custom tag `<tg-collage>`. */
+export function collage(blocks, caption = {}) {
+    return { html: `<tg-collage>${join(blocks)}${figcaption(caption)}</tg-collage>` };
+}
+/** `RichBlockSlideshow`, confirmed custom tag `<tg-slideshow>`. */
+export function slideshow(blocks, caption = {}) {
+    return { html: `<tg-slideshow>${join(blocks)}${figcaption(caption)}</tg-slideshow>` };
+}
+/** one `<td>`/`<th>` cell; `content` omitted ⇒ an invisible cell (per `RichBlockTableCell`). */
+export function cell(content, options = {}) {
+    const tag = options.header ? "th" : "td";
+    const attrs = (options.colspan ? ` colspan="${options.colspan}"` : "") +
+        (options.rowspan ? ` rowspan="${options.rowspan}"` : "") +
+        // `align`/`valign` are telegram's own field names for this cell — the values
+        // (left/center/right, top/middle/bottom) match the classic html attributes exactly.
+        (options.align ? ` align="${options.align}"` : "") +
+        (options.valign ? ` valign="${options.valign}"` : "");
+    return {
+        html: content === undefined
+            ? `<${tag}${attrs}></${tag}>`
+            : `<${tag}${attrs}>${toHtml(content)}</${tag}>`,
+    };
+}
+/** `RichBlockTable`, confirmed `<table>`. build rows with `cell()`. */
+export function table(rows, options = {}) {
+    const attrs = (options.bordered ? " border" : "") + (options.striped ? " data-striped" : "");
+    const body = rows.map((row) => `<tr>${join(row)}</tr>`).join("");
+    const captionHtml = options.caption === undefined ? "" : `<caption>${toHtml(options.caption)}</caption>`;
+    return { html: `<table${attrs}>${captionHtml}${body}</table>` };
+}
+/** `RichBlockDetails`, confirmed `<details>`/`<summary>`. */
+export function details(summary, blocks, options = {}) {
+    return {
+        html: `<details${options.open ? " open" : ""}><summary>${toHtml(summary)}</summary>${join(blocks)}</details>`,
+    };
+}
+/** one `<li>` for `list()`. */
+export function item(blocks, options = {}) {
+    const attrs = (options.value !== undefined ? ` value="${options.value}"` : "") +
+        (options.type ? ` type="${options.type}"` : "");
+    const checkboxHtml = options.checkbox === undefined
+        ? ""
+        : `<input type="checkbox"${options.checked ? " checked" : ""}/> `;
+    return { html: `<li${attrs}>${checkboxHtml}${join(blocks)}</li>` };
+}
+/** `RichBlockList`, `<ul>`/`<ol>` of `item()`s. */
+export function list(items, options = {}) {
+    const tag = options.ordered ? "ol" : "ul";
+    return { html: `<${tag}>${join(items)}</${tag}>` };
+}
+/**
+ * `RichBlockMap`, confirmed custom tag `<tg-map>` — attribute names/encoding are a
+ * best-effort guess (lat/long/zoom/width/height are telegram's own field names).
+ */
+export function map(location, options, caption = {}) {
+    const attrs = ` latitude="${location.latitude}" longitude="${location.longitude}"` +
+        ` zoom="${options.zoom}" width="${options.width}" height="${options.height}"`;
+    return { html: `<tg-map${attrs}>${figcaption(caption)}</tg-map>` };
+}
+function figure(tag, src, options) {
+    const spoilerAttr = options.spoiler ? " data-media-spoiler" : "";
+    const media = `<${tag} src="${escapeAttr(src)}"${spoilerAttr}></${tag}>`;
+    const cap = figcaption(options);
+    return { html: cap ? `<figure>${media}${cap}</figure>` : media };
+}
+/**
+ * `RichBlockPhoto`, confirmed `<img>`. media is referenced by url — `sendRichMessage`
+ * has no multipart/`attach://` upload path (unlike `sendPhoto`), so there is no
+ * `MediaSource` overload here; host the file and pass its url.
+ */
+export function image(src, options = {}) {
+    return figure("img", src, options);
+}
+/**
+ * `RichBlockVideo` **and** `RichBlockAnimation` both map to `<video>` per the
+ * schema (telegram tells the two apart server-side, e.g. by looping/silence —
+ * not by tag). there is no separate `animation()` builder for that reason.
+ */
+export function video(src, options = {}) {
+    return figure("video", src, options);
+}
+/**
+ * `RichBlockAudio` **and** `RichBlockVoiceNote` both map to `<audio>` per the
+ * schema (again disambiguated server-side, not by tag) — there is no separate
+ * `voiceNote()` builder for that reason.
+ */
+export function audio(src, options = {}) {
+    return figure("audio", src, options);
+}
+/**
+ * `RichBlockThinking`, confirmed custom tag `<tg-thinking>`. **draft-only** — the
+ * schema states it can be used in `sendRichMessageDraft` payloads but is never
+ * received back on a real message. see `RichMessageDraft` in draft.ts.
+ */
+export function thinking(...children) {
+    return { html: `<tg-thinking>${join(children)}</tg-thinking>` };
+}
+//# sourceMappingURL=blocks.js.map

package/lib/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}

package/lib/draft.d.ts

@@ -0,0 +1,44 @@
+import type { Api, Message } from "@yaebal/core";
+import type { InputRichMessage } from "@yaebal/types";
+export interface RichMessageDraftOptions {
+    /**
+     * how often to re-push the last draft to keep it alive, in ms. telegram drops
+     * a draft 30s after the last `sendRichMessageDraft` call for its `draft_id`
+     * ("ephemeral … temporary 30-second preview"); this must stay comfortably
+     * under that. defaults to 20_000.
+     */
+    keepAliveMs?: number;
+    /** called when a background keep-alive push fails (e.g. network blip). */
+    onError?: (error: unknown) => void;
+}
+/**
+ * a `sendRichMessageDraft` streaming session — the operationally hard part of the
+ * rich-message api. telegram's draft is ephemeral: it vanishes 30s after the last
+ * push, and it never turns into a real message on its own (per the schema:
+ * "once the output is finalized, you must call sendRichMessage with the complete
+ * message to persist it"). this class:
+ *
+ * - re-pushes the latest draft on a timer so a slow generator (e.g. an LLM
+ *   stream) doesn't lose the draft between tokens;
+ * - refuses to push after `commit()`/`cancel()`, so a stray late token can't
+ *   resurrect a closed draft;
+ * - requires an explicit `commit()` — there is no implicit "last push wins".
+ *
+ * @example
+ * const draft = ctx.richMessageDraft(1);
+ * await draft.push(thinking("…"));
+ * for await (const chunk of stream) await draft.push(document([paragraph(soFar)]));
+ * await draft.commit(document([paragraph(finalAnswer)]));
+ */
+export declare class RichMessageDraft {
+    #private;
+    constructor(api: Api, chatId: number, draftId: number, options?: RichMessageDraftOptions);
+    get closed(): boolean;
+    /** push a new partial draft; telegram animates the transition for a shared `draft_id`. */
+    push(input: InputRichMessage | string): Promise<void>;
+    /** finalize: persist the real message and stop the keep-alive. always call this or `cancel()`. */
+    commit(input: InputRichMessage | string, extra?: Record<string, unknown>): Promise<Message>;
+    /** abandon the draft without persisting anything — it expires within 30s on its own. */
+    cancel(): void;
+}
+//# sourceMappingURL=draft.d.ts.map

package/lib/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;;gBAWhB,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B;IAQ5F,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,0FAA0F;IACpF,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B3D,kGAAkG;IAC5F,MAAM,CACX,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAChC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,OAAO,CAAC;IAYnB,wFAAwF;IACxF,MAAM,IAAI,IAAI;CAUd"}

package/lib/draft.js

@@ -0,0 +1,85 @@
+/**
+ * a `sendRichMessageDraft` streaming session — the operationally hard part of the
+ * rich-message api. telegram's draft is ephemeral: it vanishes 30s after the last
+ * push, and it never turns into a real message on its own (per the schema:
+ * "once the output is finalized, you must call sendRichMessage with the complete
+ * message to persist it"). this class:
+ *
+ * - re-pushes the latest draft on a timer so a slow generator (e.g. an LLM
+ *   stream) doesn't lose the draft between tokens;
+ * - refuses to push after `commit()`/`cancel()`, so a stray late token can't
+ *   resurrect a closed draft;
+ * - requires an explicit `commit()` — there is no implicit "last push wins".
+ *
+ * @example
+ * const draft = ctx.richMessageDraft(1);
+ * await draft.push(thinking("…"));
+ * for await (const chunk of stream) await draft.push(document([paragraph(soFar)]));
+ * await draft.commit(document([paragraph(finalAnswer)]));
+ */
+export class RichMessageDraft {
+    #api;
+    #chatId;
+    #draftId;
+    #keepAliveMs;
+    #onError;
+    #timer;
+    #latest;
+    #closed = false;
+    constructor(api, chatId, draftId, options = {}) {
+        this.#api = api;
+        this.#chatId = chatId;
+        this.#draftId = draftId;
+        this.#keepAliveMs = options.keepAliveMs ?? 20_000;
+        this.#onError = options.onError;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    /** push a new partial draft; telegram animates the transition for a shared `draft_id`. */
+    async push(input) {
+        if (this.#closed)
+            throw new Error("RichMessageDraft: push() after commit()/cancel()");
+        const resolved = typeof input === "string" ? { html: input } : input;
+        this.#latest = resolved;
+        await this.#push(resolved);
+        this.#arm();
+    }
+    #push(input) {
+        return this.#api.call("sendRichMessageDraft", {
+            chat_id: this.#chatId,
+            draft_id: this.#draftId,
+            rich_message: input,
+        });
+    }
+    #arm() {
+        clearInterval(this.#timer);
+        this.#timer = setInterval(() => {
+            if (!this.#latest)
+                return;
+            this.#push(this.#latest).catch((error) => this.#onError?.(error));
+        }, this.#keepAliveMs);
+        this.#timer.unref?.();
+    }
+    /** finalize: persist the real message and stop the keep-alive. always call this or `cancel()`. */
+    async commit(input, extra = {}) {
+        this.#stop();
+        const resolved = typeof input === "string" ? { html: input } : input;
+        return this.#api.call("sendRichMessage", {
+            chat_id: this.#chatId,
+            rich_message: resolved,
+            ...extra,
+        });
+    }
+    /** abandon the draft without persisting anything — it expires within 30s on its own. */
+    cancel() {
+        this.#stop();
+    }
+    #stop() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        clearInterval(this.#timer);
+    }
+}
+//# sourceMappingURL=draft.js.map

package/lib/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,CAAM;IACV,OAAO,CAAS;IAChB,QAAQ,CAAS;IACjB,YAAY,CAAS;IACrB,QAAQ,CAA4B;IAE7C,MAAM,CAAkC;IACxC,OAAO,CAA+B;IACtC,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAY,GAAQ,EAAE,MAAc,EAAE,OAAe,EAAE,UAAmC,EAAE;QAC3F,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,IAAI,CAAC,KAAgC;QAC1C,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAEtF,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAErE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;IACb,CAAC;IAED,KAAK,CAAC,KAAuB;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAU,sBAAsB,EAAE;YACtD,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,KAAK;SACnB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI;QACH,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE3B,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;YAC9B,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,OAAO;YAE1B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAEtB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IAED,kGAAkG;IAClG,KAAK,CAAC,MAAM,CACX,KAAgC,EAChC,QAAiC,EAAE;QAEnC,IAAI,CAAC,KAAK,EAAE,CAAC;QAEb,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAErE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAU,iBAAiB,EAAE;YACjD,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,YAAY,EAAE,QAAQ;YACtB,GAAG,KAAK;SACR,CAAC,CAAC;IACJ,CAAC;IAED,wFAAwF;IACxF,MAAM;QACL,IAAI,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;IAED,KAAK;QACJ,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;CACD"}

package/lib/escape.d.ts

@@ -0,0 +1,5 @@
+/** escape text so it can never be re-parsed as a tag or entity. */
+export declare function escapeText(value: string): string;
+/** escape a double-quoted attribute value. */
+export declare function escapeAttr(value: string): string;
+//# sourceMappingURL=escape.d.ts.map

package/lib/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/lib/escape.js

@@ -0,0 +1,9 @@
+/** escape text so it can never be re-parsed as a tag or entity. */
+export function escapeText(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** escape a double-quoted attribute value. */
+export function escapeAttr(value) {
+    return escapeText(value).replace(/"/g, "&quot;");
+}
+//# sourceMappingURL=escape.js.map

package/lib/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACjF,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC"}