From 50c18574add2abee417a23ea94e6d4d35f87be71 Mon Sep 17 00:00:00 2001 From: Steve Dempsey Date: Thu, 12 Nov 2026 12:20:28 -0500 Subject: [PATCH] Lay out IM cards: two sentences per paragraph, spaced lists Cards reached chat apps as walls of text: long questions ran on, and the option list started on the line straight after the question. sendCard now lays every card out before it is sent and recorded, whichever Bot wrote it: a paragraph of more than two sentences breaks after every second sentence, and a list gets a blank line before its first item and between items. Only whitespace changes. Decimals, versions, URLs, inline code, common abbreviations, fences, headings, tables and the list items themselves are left as written; button labels are not touched. --- ds-bot/src/host/im/format.js | 74 +++++++++++++++++++++++++++++++++++ ds-bot/src/host/im/index.js | 5 ++- ds-bot/test/im-format.test.js | 40 ++++++++++++++++++- ds-bot/test/im.test.js | 14 ++++++- 4 files changed, 130 insertions(+), 3 deletions(-) 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)