@llblab/pi-telegram 0.2.8 → 0.2.9

package/tests/preview.test.ts

@@ -0,0 +1,441 @@
+/**
+ * Regression tests for the Telegram preview domain
+ * Covers preview snapshot decisions, transport selection, runtime flushing, and finalization behavior
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildTelegramPreviewFlushText,
+  buildTelegramPreviewSnapshot,
+  renderTelegramMessage,
+  type TelegramRenderedChunk,
+  type TelegramRenderMode,
+} from "../lib/rendering.ts";
+import {
+  buildTelegramPreviewFinalText,
+  clearTelegramPreview,
+  finalizeTelegramMarkdownPreview,
+  finalizeTelegramPreview,
+  flushTelegramPreview,
+  shouldUseTelegramDraftPreview,
+} from "../lib/preview.ts";
+
+function createPreviewRuntimeHarness(state?: {
+  mode: "draft" | "message";
+  draftId?: number;
+  messageId?: number;
+  pendingText: string;
+  lastSentText: string;
+  lastSentParseMode?: "HTML";
+  lastSentStrategy?: "plain" | "rich-stable-blocks";
+  flushTimer?: ReturnType<typeof setTimeout>;
+}) {
+  let previewState = state;
+  let draftSupport: "unknown" | "supported" | "unsupported" = "unknown";
+  let nextDraftId = 10;
+  const events: string[] = [];
+  return {
+    events,
+    getState: () => previewState,
+    getDraftSupport: () => draftSupport,
+    setDraftSupport: (support: "unknown" | "supported" | "unsupported") => {
+      draftSupport = support;
+    },
+    deps: {
+      getState: () => previewState,
+      setState: (nextState: typeof previewState) => {
+        previewState = nextState;
+      },
+      clearScheduledFlush: (nextState: NonNullable<typeof previewState>) => {
+        if (!nextState.flushTimer) return;
+        clearTimeout(nextState.flushTimer);
+        nextState.flushTimer = undefined;
+        events.push("clear-timer");
+      },
+      maxMessageLength: 50,
+      renderPreviewText: (markdown: string) => markdown.replaceAll("*", ""),
+      getDraftSupport: () => draftSupport,
+      setDraftSupport: (support: "unknown" | "supported" | "unsupported") => {
+        draftSupport = support;
+      },
+      allocateDraftId: () => nextDraftId++,
+      sendDraft: async (chatId: number, draftId: number, text: string) => {
+        events.push(`draft:${chatId}:${draftId}:${text}`);
+      },
+      sendMessage: async (
+        chatId: number,
+        text: string,
+        options?: { parseMode?: "HTML" },
+      ) => {
+        events.push(`send:${chatId}:${text}:${options?.parseMode ?? "plain"}`);
+        return { message_id: 77 };
+      },
+      editMessageText: async (
+        chatId: number,
+        messageId: number,
+        text: string,
+        options?: { parseMode?: "HTML" },
+      ) => {
+        events.push(
+          `edit:${chatId}:${messageId}:${text}:${options?.parseMode ?? "plain"}`,
+        );
+      },
+      renderTelegramMessage: (
+        text: string,
+        options?: { mode?: TelegramRenderMode },
+      ): TelegramRenderedChunk[] =>
+        options?.mode === "markdown"
+          ? [{ text: `markdown:${text}`, parseMode: "HTML" as const }]
+          : [{ text: `${options?.mode ?? "plain"}:${text}` }],
+      sendRenderedChunks: async (
+        chatId: number,
+        chunks: Array<{ text: string }>,
+      ) => {
+        events.push(
+          `render-send:${chatId}:${chunks.map((chunk) => chunk.text).join("|")}`,
+        );
+        return 88;
+      },
+      editRenderedMessage: async (
+        chatId: number,
+        messageId: number,
+        chunks: Array<{ text: string }>,
+      ) => {
+        events.push(
+          `render-edit:${chatId}:${messageId}:${chunks.map((chunk) => chunk.text).join("|")}`,
+        );
+        return messageId;
+      },
+    },
+  };
+}
+
+test("Preview helpers build flush text only when the preview changed", () => {
+  assert.equal(
+    buildTelegramPreviewFlushText({
+      state: {
+        pendingText: "**hello**",
+        lastSentText: "",
+      },
+      maxMessageLength: 4096,
+      renderPreviewText: (markdown) => markdown.replaceAll("*", ""),
+    }),
+    "hello",
+  );
+  assert.equal(
+    buildTelegramPreviewFlushText({
+      state: {
+        pendingText: "**hello**",
+        lastSentText: "hello",
+      },
+      maxMessageLength: 4096,
+      renderPreviewText: (markdown) => markdown.replaceAll("*", ""),
+    }),
+    undefined,
+  );
+});
+
+test("Preview snapshots prefer stable rich blocks and fall back to plain text", () => {
+  const richSnapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "```ts\nconst value = 1\n```",
+      lastSentText: "",
+    },
+    maxMessageLength: 100,
+    renderPreviewText: (markdown) => markdown.replaceAll("*", ""),
+    renderTelegramMessage: (text, options) =>
+      options?.mode === "markdown"
+        ? [{ text: `<b>${text}</b>`, parseMode: "HTML" as const }]
+        : [{ text }],
+  });
+  assert.deepEqual(richSnapshot, {
+    text: "<b>```ts\nconst value = 1\n```</b>",
+    parseMode: "HTML",
+    sourceText: "```ts\nconst value = 1\n```",
+    strategy: "rich-stable-blocks",
+  });
+  const plainSnapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "**hello**",
+      lastSentText: "",
+    },
+    maxMessageLength: 5,
+    renderPreviewText: (markdown) => markdown.replaceAll("*", ""),
+    renderTelegramMessage: () => [
+      { text: "markdown:too-long", parseMode: "HTML" as const },
+    ],
+  });
+  assert.deepEqual(plainSnapshot, {
+    text: "hello",
+    sourceText: "**hello**",
+    strategy: "plain",
+  });
+});
+
+test("Preview snapshots append conservative plain tails for incomplete fences, quotes, and lists", () => {
+  const renderTelegramMessage = (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) =>
+    options?.mode === "markdown"
+      ? [{ text: `<b>${text}</b>`, parseMode: "HTML" as const }]
+      : [{ text }];
+  const fenceSnapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "## Intro\n\n```ts\nconst value = 1",
+      lastSentText: "",
+    },
+    maxMessageLength: 200,
+    renderPreviewText: (markdown) => markdown,
+    renderTelegramMessage,
+  });
+  assert.deepEqual(fenceSnapshot, {
+    text: "<b>## Intro</b>\n\n```ts\nconst value = 1",
+    parseMode: "HTML",
+    sourceText: "## Intro\n\n```ts\nconst value = 1",
+    strategy: "rich-stable-blocks",
+  });
+  const quoteSnapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "## Intro\n\n\n> quoted line",
+      lastSentText: "",
+    },
+    maxMessageLength: 200,
+    renderPreviewText: (markdown) => markdown,
+    renderTelegramMessage,
+  });
+  assert.deepEqual(quoteSnapshot, {
+    text: "<b>## Intro</b>\n\n\n&gt; quoted line",
+    parseMode: "HTML",
+    sourceText: "## Intro\n\n\n> quoted line",
+    strategy: "rich-stable-blocks",
+  });
+  const listSnapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "## Intro\n\n\n- first\n- second",
+      lastSentText: "",
+    },
+    maxMessageLength: 200,
+    renderPreviewText: (markdown) => markdown,
+    renderTelegramMessage,
+  });
+  assert.deepEqual(listSnapshot, {
+    text: "<b>## Intro</b>\n\n\n- first\n- second",
+    parseMode: "HTML",
+    sourceText: "## Intro\n\n\n- first\n- second",
+    strategy: "rich-stable-blocks",
+  });
+});
+
+test("Preview snapshots omit unstable tails when long-message limits leave no room", () => {
+  const snapshot = buildTelegramPreviewSnapshot({
+    state: {
+      pendingText: "## Intro\n\n- first\n- second\n- third",
+      lastSentText: "",
+    },
+    maxMessageLength: 18,
+    renderPreviewText: (markdown) => markdown,
+    renderTelegramMessage: (text, options) =>
+      options?.mode === "markdown"
+        ? [{ text: `<b>${text}</b>`, parseMode: "HTML" as const }]
+        : [{ text }],
+  });
+  assert.deepEqual(snapshot, {
+    text: "<b>## Intro</b>",
+    parseMode: "HTML",
+    sourceText: "## Intro\n\n- first\n- second\n- third",
+    strategy: "rich-stable-blocks",
+  });
+});
+
+test("Preview helpers compute final text fallback without reusing rich HTML snapshots", () => {
+  assert.equal(
+    buildTelegramPreviewFinalText({
+      mode: "message",
+      pendingText: "   ",
+      lastSentText: "saved",
+      lastSentStrategy: "plain",
+    }),
+    "saved",
+  );
+  assert.equal(
+    buildTelegramPreviewFinalText({
+      mode: "message",
+      pendingText: "   ",
+      lastSentText: "<b>saved</b>",
+      lastSentParseMode: "HTML",
+      lastSentStrategy: "rich-stable-blocks",
+    }),
+    undefined,
+  );
+  assert.equal(
+    buildTelegramPreviewFinalText({
+      mode: "message",
+      pendingText: "   ",
+      lastSentText: "   ",
+    }),
+    undefined,
+  );
+});
+
+test("Preview helpers use drafts only for plain preview snapshots", () => {
+  assert.equal(
+    shouldUseTelegramDraftPreview({ draftSupport: "unknown" }),
+    true,
+  );
+  assert.equal(
+    shouldUseTelegramDraftPreview({
+      draftSupport: "supported",
+      snapshot: { text: "preview", sourceText: "preview", strategy: "plain" },
+    }),
+    true,
+  );
+  assert.equal(
+    shouldUseTelegramDraftPreview({
+      draftSupport: "supported",
+      snapshot: {
+        text: "<b>preview</b>",
+        parseMode: "HTML",
+        sourceText: "preview",
+        strategy: "rich-stable-blocks",
+      },
+    }),
+    false,
+  );
+  assert.equal(
+    shouldUseTelegramDraftPreview({ draftSupport: "unsupported" }),
+    false,
+  );
+});
+
+test("Preview runtime prefers editable rich previews when stable blocks are available", async () => {
+  const harness = createPreviewRuntimeHarness({
+    mode: "draft",
+    pendingText: "## Intro\n\nTail",
+    lastSentText: "",
+    flushTimer: setTimeout(() => {}, 1000),
+  });
+  await flushTelegramPreview(7, harness.deps);
+  assert.deepEqual(harness.events, ["send:7:markdown:## Intro\n\nTail:HTML"]);
+  assert.equal(harness.getState()?.mode, "message");
+  assert.equal(harness.getState()?.messageId, 77);
+  assert.equal(harness.getState()?.lastSentText, "markdown:## Intro\n\nTail");
+  assert.equal(harness.getState()?.lastSentParseMode, "HTML");
+  assert.equal(harness.getState()?.lastSentStrategy, "rich-stable-blocks");
+  assert.equal(harness.getDraftSupport(), "unknown");
+});
+
+test("Preview runtime preserves original blank-line spacing around conservative tails", async () => {
+  const cases = [
+    {
+      markdown: "Para\n\n\n> Quote",
+      expectedEvent: "send:7:markdown:Para\n\n\n&gt; Quote:HTML",
+      expectedText: "markdown:Para\n\n\n&gt; Quote",
+    },
+    {
+      markdown: "Para\n\n\n- item",
+      expectedEvent: "send:7:markdown:Para\n\n\n- item:HTML",
+      expectedText: "markdown:Para\n\n\n- item",
+    },
+  ];
+  for (const testCase of cases) {
+    const harness = createPreviewRuntimeHarness({
+      mode: "draft",
+      pendingText: testCase.markdown,
+      lastSentText: "",
+      flushTimer: setTimeout(() => {}, 1000),
+    });
+    await flushTelegramPreview(7, harness.deps);
+    assert.deepEqual(harness.events, [testCase.expectedEvent]);
+    assert.equal(harness.getState()?.lastSentText, testCase.expectedText);
+  }
+});
+
+test("Preview runtime keeps heading-to-code spacing readable without source blank lines", async () => {
+  const harness = createPreviewRuntimeHarness({
+    mode: "draft",
+    pendingText: "### Title\n```ts\nconst x = 1\n```",
+    lastSentText: "",
+    flushTimer: setTimeout(() => {}, 1000),
+  });
+  harness.deps.renderTelegramMessage = renderTelegramMessage;
+  harness.deps.maxMessageLength = 4096;
+  await flushTelegramPreview(7, harness.deps);
+  assert.deepEqual(harness.events, [
+    'send:7:<b>Title</b>\n\n<pre><code class="language-ts">const x = 1</code></pre>:HTML',
+  ]);
+  assert.equal(
+    harness.getState()?.lastSentText,
+    '<b>Title</b>\n\n<pre><code class="language-ts">const x = 1</code></pre>',
+  );
+});
+
+test("Preview runtime can still use and clear plain draft previews", async () => {
+  const harness = createPreviewRuntimeHarness({
+    mode: "draft",
+    pendingText: "**hello**",
+    lastSentText: "",
+    flushTimer: setTimeout(() => {}, 1000),
+  });
+  harness.deps.renderTelegramMessage = () => [];
+  await flushTelegramPreview(7, harness.deps);
+  assert.deepEqual(harness.events, ["draft:7:10:hello"]);
+  assert.equal(harness.getState()?.mode, "draft");
+  assert.equal(harness.getState()?.draftId, 10);
+  assert.equal(harness.getState()?.lastSentText, "hello");
+  assert.equal(harness.getState()?.lastSentStrategy, "plain");
+  assert.equal(harness.getDraftSupport(), "supported");
+  await clearTelegramPreview(7, harness.deps);
+  assert.deepEqual(harness.events, ["draft:7:10:hello", "draft:7:10:"]);
+  assert.equal(harness.getState(), undefined);
+});
+
+test("Preview runtime falls back to editable plain messages when draft delivery fails", async () => {
+  const harness = createPreviewRuntimeHarness({
+    mode: "draft",
+    pendingText: "abcdef",
+    lastSentText: "",
+  });
+  harness.deps.renderTelegramMessage = () => [];
+  harness.deps.sendDraft = async () => {
+    throw new Error("draft unsupported");
+  };
+  await flushTelegramPreview(7, harness.deps);
+  assert.deepEqual(harness.events, ["send:7:abcdef:plain"]);
+  assert.equal(harness.getState()?.mode, "message");
+  assert.equal(harness.getState()?.messageId, 77);
+  assert.equal(harness.getState()?.lastSentStrategy, "plain");
+  assert.equal(harness.getDraftSupport(), "unsupported");
+});
+
+test("Preview runtime finalizes plain and markdown previews", async () => {
+  const plainHarness = createPreviewRuntimeHarness({
+    mode: "message",
+    messageId: 44,
+    pendingText: "done",
+    lastSentText: "",
+  });
+  plainHarness.setDraftSupport("unsupported");
+  plainHarness.deps.renderTelegramMessage = () => [];
+  assert.equal(await finalizeTelegramPreview(7, plainHarness.deps), true);
+  assert.deepEqual(plainHarness.events, ["edit:7:44:done:plain"]);
+  assert.equal(plainHarness.getState(), undefined);
+  const markdownHarness = createPreviewRuntimeHarness({
+    mode: "message",
+    messageId: 55,
+    pendingText: "done",
+    lastSentText: "",
+  });
+  markdownHarness.setDraftSupport("unsupported");
+  assert.equal(
+    await finalizeTelegramMarkdownPreview(7, "**done**", markdownHarness.deps),
+    true,
+  );
+  assert.deepEqual(markdownHarness.events, [
+    "edit:7:55:done:plain",
+    "render-edit:7:55:markdown:**done**",
+  ]);
+  assert.equal(markdownHarness.getState(), undefined);
+});

package/tests/queue.test.ts

@@ -1154,6 +1154,7 @@ test("Extension runtime finalizes a drafted preview into the final Telegram repl
   });
   const draftTexts: string[] = [];
   const sentTexts: string[] = [];
+  const editedTexts: string[] = [];
   const pi = {
     on: (
       event: string,
@@ -1225,6 +1226,7 @@ test("Extension runtime finalizes a drafted preview into the final Telegram repl
       return { json: async () => ({ ok: true, result: true }) } as Response;
     }
     if (method === "editMessageText") {
+      editedTexts.push(String(body?.text ?? ""));
       return { json: async () => ({ ok: true, result: true }) } as Response;
     }
     throw new Error(`Unexpected Telegram API method: ${method}`);
@@ -1284,6 +1286,7 @@ test("Extension runtime finalizes a drafted preview into the final Telegram repl
     assert.deepEqual(draftTexts, ["Draft preview", "Final answer", ""]);
     assert.equal(sentTexts.length, 1);
     assert.match(sentTexts[0] ?? "", /Final <b>answer<\/b>/);
+    assert.deepEqual(editedTexts, []);
     await handlers.get("session_shutdown")?.({}, ctx);
   } finally {
     globalThis.fetch = originalFetch;

package/tests/rendering.test.ts

@@ -7,7 +7,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { __telegramTestUtils } from "../index.ts";
-import { renderMarkdownPreviewText } from "../lib/rendering.ts";
+import {
+  buildTelegramPreviewSnapshot,
+  renderMarkdownPreviewText,
+} from "../lib/rendering.ts";
 
 test("Nested lists stay out of code blocks", () => {
   const chunks = __telegramTestUtils.renderTelegramMessage(
@@ -93,13 +96,88 @@ test("Leading indentation on the first markdown line stays intact", () => {
     mode: "markdown",
   });
   assert.equal(chunks.length, 1);
-  assert.match(chunks[0]?.text ?? "", /^\u00A0\u00A0<code>-<\/code> nested bullet/m);
+  assert.match(
+    chunks[0]?.text ?? "",
+    /^\u00A0\u00A0<code>-<\/code> nested bullet/m,
+  );
   assert.match(
     chunks[0]?.text ?? "",
     /^\u00A0\u00A0\u00A0\u00A0<code>-<\/code> nested child/m,
   );
 });
 
+test("Preview and final rendering preserve multiple blank lines between blocks", () => {
+  const markdown = "# Title\n\n\nParagraph\n\n\n> Quote";
+  assert.equal(
+    renderMarkdownPreviewText(markdown),
+    "Title\n\n\nParagraph\n\n\n> Quote",
+  );
+  const chunks = __telegramTestUtils.renderTelegramMessage(markdown, {
+    mode: "markdown",
+  });
+  assert.equal(chunks.length, 1);
+  assert.match(
+    chunks[0]?.text ?? "",
+    /<b>Title<\/b>\n\n\nParagraph\n\n\n<blockquote>Quote<\/blockquote>/,
+  );
+});
+
+test("Rendering preserves original blank-line spacing across block transitions", () => {
+  const cases = [
+    {
+      markdown: "Para\n\n\n```ts\nconst x = 1\n```",
+      finalText:
+        'Para\n\n\n<pre><code class="language-ts">const x = 1</code></pre>',
+      previewText:
+        'Para\n\n\n<pre><code class="language-ts">const x = 1</code></pre>',
+    },
+    {
+      markdown: "```ts\nconst x = 1\n```\n\n\nPara",
+      finalText:
+        '<pre><code class="language-ts">const x = 1</code></pre>\n\n\nPara',
+      previewText:
+        '<pre><code class="language-ts">const x = 1</code></pre>\n\n\nPara',
+    },
+    {
+      markdown: "Para\n\n\n- item",
+      finalText: "Para\n\n\n<code>-</code> item",
+      previewText: "Para\n\n\n- item",
+    },
+    {
+      markdown: "Para\n\n\n> Quote",
+      finalText: "Para\n\n\n<blockquote>Quote</blockquote>",
+      previewText: "Para\n\n\n&gt; Quote",
+    },
+  ];
+  for (const testCase of cases) {
+    const finalChunks = __telegramTestUtils.renderTelegramMessage(
+      testCase.markdown,
+      { mode: "markdown" },
+    );
+    assert.equal(finalChunks.length, 1);
+    assert.equal(finalChunks[0]?.text ?? "", testCase.finalText);
+    const preview = buildTelegramPreviewSnapshot({
+      state: { pendingText: testCase.markdown, lastSentText: "" },
+      maxMessageLength: __telegramTestUtils.MAX_MESSAGE_LENGTH,
+      renderPreviewText: renderMarkdownPreviewText,
+      renderTelegramMessage: __telegramTestUtils.renderTelegramMessage,
+    });
+    assert.equal(preview?.text ?? "", testCase.previewText);
+  }
+});
+
+test("Headings keep visible spacing before following code blocks even without source blank lines", () => {
+  const markdown = "### Title\n```ts\nconst x = 1\n```";
+  const chunks = __telegramTestUtils.renderTelegramMessage(markdown, {
+    mode: "markdown",
+  });
+  assert.equal(chunks.length, 1);
+  assert.match(
+    chunks[0]?.text ?? "",
+    /<b>Title<\/b>\n\n<pre><code class="language-ts">const x = 1<\/code><\/pre>/,
+  );
+});
+
 test("Standalone checkbox-looking prose stays literal outside task lists", () => {
   const markdown = "Use [ ] as a placeholder and keep [x] literal";
   assert.equal(renderMarkdownPreviewText(markdown), markdown);
@@ -154,6 +232,50 @@ test("Links, code spans, and underscore-heavy text coexist safely", () => {
   assert.equal((chunks[0]?.text ?? "").includes("<i>bar</i>"), false);
 });
 
+test("Links degrade or normalize safely across supported and unsupported markdown forms", () => {
+  const markdown = [
+    "[**Bold** label](https://example.com/path)",
+    "[Docs](https://example.com/a_(b))",
+    '[Title](https://example.com/path "Tooltip")',
+    "[Relative](./docs/README.md)",
+    "[Ref][docs]",
+    "",
+    "[docs]: https://example.com/ref",
+    "",
+    "Footnote[^1]",
+    "",
+    "[^1]: Footnote body",
+  ].join("\n");
+  const chunks = __telegramTestUtils.renderTelegramMessage(markdown, {
+    mode: "markdown",
+  });
+  assert.equal(chunks.length, 1);
+  assert.match(
+    chunks[0]?.text ?? "",
+    /<a href="https:\/\/example.com\/path">Bold label<\/a>/,
+  );
+  assert.match(
+    chunks[0]?.text ?? "",
+    /<a href="https:\/\/example.com\/a_\(b\)">Docs<\/a>/,
+  );
+  assert.match(
+    chunks[0]?.text ?? "",
+    /<a href="https:\/\/example.com\/path">Title<\/a>/,
+  );
+  assert.equal(
+    (chunks[0]?.text ?? "").includes('<a href="./docs/README.md">'),
+    false,
+  );
+  assert.match(chunks[0]?.text ?? "", /Relative/);
+  assert.equal(
+    (chunks[0]?.text ?? "").includes('<a href="https://example.com/ref">'),
+    false,
+  );
+  assert.match(chunks[0]?.text ?? "", /\[Ref\]\[docs\]/);
+  assert.match(chunks[0]?.text ?? "", /Footnote\[\^1\]/);
+  assert.match(chunks[0]?.text ?? "", /\[\^1\]: Footnote body/);
+});
+
 test("Long quoted blocks stay chunked with balanced blockquote tags", () => {
   const markdown = Array.from(
     { length: 500 },