diff --git a/ds-bot/src/host/im/format.js b/ds-bot/src/host/im/format.js
index 835a22d2f0..8e9320ab97 100644
--- a/ds-bot/src/host/im/format.js
+++ b/ds-bot/src/host/im/format.js
@@ -276,6 +276,80 @@ export function chunkMarkdown(markdown, limit) {
return chunks
}
+// Card layout (Steve, 2026-11-12): at most two sentences per paragraph, and a blank
+// line before the first list item and between items. Only whitespace changes: a
+// sentence boundary inside a long paragraph becomes a blank line. A boundary is .!?
+// followed by space and a capital letter, or a CJK full stop, so decimals, versions
+// and URLs never split; inline code, fences, headings, tables and list items are
+// left as they are.
+const SENTENCE_GAP = /(?<=[.!?]["'”’)\]]*)(\s+)(?=["'“‘([]?\p{Lu})|(?<=[。!?])()(?=\S)/gu
+const SENTENCE_END = /(?:[.!?]["'”’)\]]*|[。!?])\s*$/u
+// A full stop after one of these ends no sentence.
+const ABBREVIATION = /\b(?:Mr|Mrs|Ms|Dr|St|Jr|Sr|vs|etc|Inc|Ltd|No|e\.g|i\.e)\.["'”’)\]]*\s*$/i
+
+function layoutParagraph(lines) {
+ const pieces = []
+ for (const line of lines) {
+ // Code spans keep their length but can hold no sentence boundary.
+ const masked = line.replace(/`[^`]*`/g, span => '\u0001'.repeat(span.length))
+ let from = 0
+ for (const gap of masked.matchAll(SENTENCE_GAP)) {
+ if (ABBREVIATION.test(masked.slice(0, gap.index))) continue
+ pieces.push({ text: line.slice(from, gap.index), ends: true, sep: line.slice(gap.index, gap.index + gap[0].length) })
+ from = gap.index + gap[0].length
+ }
+ pieces.push({ text: line.slice(from), ends: SENTENCE_END.test(masked) && !ABBREVIATION.test(masked), sep: '\n' })
+ }
+ let count = 0
+ let out = ''
+ for (const [index, piece] of pieces.entries()) {
+ out += piece.text
+ if (index === pieces.length - 1) break
+ if (piece.ends) count += 1
+ if (piece.ends && count === 2) {
+ out += '\n\n'
+ count = 0
+ } else {
+ out += piece.sep
+ }
+ }
+ return out
+}
+
+export function cardLayout(markdown) {
+ const out = []
+ let paragraph = []
+ let fenced = false
+ const flush = () => {
+ if (paragraph.length > 0) out.push(layoutParagraph(paragraph))
+ paragraph = []
+ }
+ for (const line of String(markdown ?? '').split('\n')) {
+ if (line.startsWith('```')) {
+ flush()
+ fenced = !fenced
+ out.push(line)
+ continue
+ }
+ if (fenced) { out.push(line); continue }
+ if (line.trim() === '') { flush(); out.push(line); continue }
+ if (isListItem(line)) {
+ flush()
+ if (out.length > 0 && out.at(-1).trim() !== '') out.push('')
+ out.push(line)
+ continue
+ }
+ if (HEADING_RE.test(line) || isRule(line) || isTableRow(line)) {
+ flush()
+ out.push(line)
+ continue
+ }
+ paragraph.push(line)
+ }
+ flush()
+ return out.join('\n')
+}
+
export function chunkTelegram(markdown, limit = 4096) {
const chunks = []
let html = ''
diff --git a/ds-bot/src/host/im/index.js b/ds-bot/src/host/im/index.js
index 2d4aba1000..7b4a48f3a4 100644
--- a/ds-bot/src/host/im/index.js
+++ b/ds-bot/src/host/im/index.js
@@ -7,6 +7,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { replaceFile } from '../files.js'
import { viewCardText } from '../parts.js'
+import { cardLayout } from './format.js'
import { imPlatform, IM_PLATFORMS } from '../../shared/im-platforms.js'
import { adapters } from './platforms/index.js'
@@ -696,7 +697,9 @@ export function install(rt) {
approval: (id) => [{ data: `a:${id}:allow`, label: text('allow') }, { data: `a:${id}:reject`, label: text('reject') }],
}
- const sendCard = async (conn, cardKey, targets, body, given) => {
+ const sendCard = async (conn, cardKey, targets, written, given) => {
+ // Every card is laid out here, whichever Bot wrote it.
+ const body = cardLayout(written)
// Every typeable card gets the typed-answer button here, so no caller can leave it out.
const buttons = typeable(conn, cardKey) ? [...(given ?? []), typedButton(cardKey)] : given
for (const { chatKey, chat } of targets) {
diff --git a/ds-bot/test/im-format.test.js b/ds-bot/test/im-format.test.js
index 47f09eb479..3c802f090c 100644
--- a/ds-bot/test/im-format.test.js
+++ b/ds-bot/test/im-format.test.js
@@ -1,6 +1,44 @@
import assert from 'node:assert/strict'
import { test } from 'node:test'
-import { chunkTelegram, toPlain, toTelegramHtml } from '../src/host/im/format.js'
+import { cardLayout, chunkTelegram, toPlain, toTelegramHtml } from '../src/host/im/format.js'
+
+test('card layout: a three-sentence paragraph gains exactly one break', () => {
+ assert.equal(cardLayout('One is here. Two is here. Three is here.'), 'One is here. Two is here.\n\nThree is here.')
+ assert.equal(cardLayout('A. B? C! D. E.'.replace(/(\w)/g, 'Word $1')), 'Word A. Word B?\n\nWord C! Word D.\n\nWord E.')
+})
+
+test('card layout: sentences across lines count toward the same paragraph', () => {
+ assert.equal(cardLayout('Chief asks: Ship it?\nThe build is green.\nThe tests pass.'), 'Chief asks: Ship it?\nThe build is green.\n\nThe tests pass.')
+})
+
+test('card layout: a paragraph followed straight by "1. " gains one blank line, items are spaced', () => {
+ assert.equal(cardLayout('Pick one:\n1. Ship\n2. Hold\n3. Ask me'), 'Pick one:\n\n1. Ship\n\n2. Hold\n\n3. Ask me')
+})
+
+test('card layout: decimals, URLs, versions, abbreviations and code never split', () => {
+ const kept = [
+ 'Conversion rose 17.6% after the change, see https://example.com/Report.Final?x=1.2 for detail.',
+ 'Upgrade from v0.3.5 to v0.3.6 first. Then restart. Mr. Smith agreed, e.g. Monday.',
+ 'Run `a. B. C.` then `d. E.` now. Done.',
+ ]
+ assert.equal(cardLayout(kept[0]), kept[0], 'decimal and URL are byte-identical')
+ assert.equal(cardLayout(kept[1]), 'Upgrade from v0.3.5 to v0.3.6 first. Then restart.\n\nMr. Smith agreed, e.g. Monday.')
+ assert.equal(cardLayout(kept[2]), kept[2], 'sentence ends inside inline code are not boundaries')
+})
+
+test('card layout: an option list keeps its labels, numbers and order', () => {
+ const card = 'Chief asks: Deploy?\n1. deploy to production\n2. One customer first - starts with Acme. Then the rest. Then review.\n3. Hold\n(reply with the number)'
+ const laid = cardLayout(card)
+ assert.equal(laid, 'Chief asks: Deploy?\n\n1. deploy to production\n\n2. One customer first - starts with Acme. Then the rest. Then review.\n\n3. Hold\n(reply with the number)')
+ assert.deepEqual(laid.split('\n').filter(line => /^\d\. /.test(line)), card.split('\n').filter(line => /^\d\. /.test(line)))
+})
+
+test('card layout: a single sentence, correct text and code fences are unchanged', () => {
+ for (const text of ['Just one sentence here.', 'Two here. And two.\n\nThen one.', 'Intro:\n\n1. A\n\n2. B', '```\nOne. Two. Three. Four.\n```', '', 'Chinese 第一句。第二句。']) {
+ assert.equal(cardLayout(text), text)
+ }
+ assert.equal(cardLayout('第一句。第二句。第三句。'), '第一句。第二句。\n\n第三句。')
+})
test('Markdown becomes Telegram HTML', () => {
assert.equal(toTelegramHtml('**bold** and _ital_'), 'bold and ital')
diff --git a/ds-bot/test/im.test.js b/ds-bot/test/im.test.js
index e73dd83530..45c997a992 100644
--- a/ds-bot/test/im.test.js
+++ b/ds-bot/test/im.test.js
@@ -510,7 +510,7 @@ test('a single-choice view card gets buttons, and a press answers the view', asy
const card = s.fake.sent.find(entry => entry.buttons !== undefined)
assert.ok(card, 'the view card has buttons')
assert.deepEqual(card.buttons, [{ data: 'v:v1:0', label: 'Ship' }, { data: 'v:v1:1', label: 'Hold' }, { data: 't:v:v1', label: 'Type my own answer' }])
- assert.match(card.text, /Chief asks: Ship it\?\nThe build is green\.\n1\. Ship\n2\. Hold - wait a day\n\(reply with the number\)/)
+ assert.equal(card.text, 'Chief asks: Ship it?\nThe build is green.\n\n1. Ship\n\n2. Hold - wait a day\n(reply with the number)', 'the card is laid out: a blank line before and between the options')
await s.fake.handlers.onAction({ chat: { key: 'dm-u1', kind: 'direct', title: 'U1' }, sender: { id: 'u1', name: 'U1' }, data: 'v:v1:1', messageId: 1 })
assert.equal(s.rt.state.views.a, undefined, 'the press answers the view')
assert.equal(s.agents.get('a')?.followed, 1)
@@ -596,6 +596,18 @@ test('a Telegram question card carries a fourth button that types an answer', as
assert.equal(card.buttons[3].label, 'Type my own answer')
})
+test('a long card question is split at two sentences before it is sent', async (t) => {
+ const s = await start()
+ t.after(s.stop)
+ await pairedChat(s)
+ s.rt.state.questions.a = { id: 'q9', question: 'The build is green. The tests pass. Ship it now?', options: [{ label: 'Ship' }, { label: 'Hold' }] }
+ await s.rt.save()
+ await s.flush()
+ const card = s.fake.sent.find(entry => entry.buttons !== undefined)
+ assert.equal(card.text, 'Chief asks: The build is green. The tests pass.\n\nShip it now?\n\n1. Ship\n\n2. Hold\n(reply with the number)')
+ assert.deepEqual(card.buttons.map(button => button.label), ['Ship', 'Hold', 'Type my own answer'], 'labels and order are untouched')
+})
+
test('the typed-answer button arms a reply prompt and the next text answers that card', async (t) => {
const s = await start()
t.after(s.stop)