From 34deffd164f615a0418ba536ffac791924a27bca Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 21:22:04 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Render=20written=20Markdown=20i?= =?UTF-8?q?n=20Sidekick=20chat=20and=20entry=20Output=20(#1342)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sidekick conversation bodies and the selected entry's rendered Output share a private display path over the pinned Marked lexer: headings, emphasis, list markers, link labels and code are styled runs, fences stay literal line for line, and unsupported constructs read as written. Controls are made inert before lexing and on every run. Retained text and raw reads are unchanged. Co-Authored-By: Claude Opus 5.5 --- .../fixtures/repl-sidekick-markdown.md | 70 +++ .../repl-bench/journeys/repl-markdown.test.md | 42 ++ packages/cli/src/repl/application.ts | 152 +++++-- packages/cli/src/repl/fitting.ts | 2 +- packages/cli/src/repl/markdown.ts | 291 ++++++++++++ packages/cli/src/repl/presentation-style.ts | 29 +- packages/cli/src/repl/source-reading.ts | 30 +- .../cli/tests/repl-sidekick-journey.test.ts | 415 ++++++++++++++++++ .../cli/tests/repl-source-reading.test.ts | 73 +++ specs/repl-spec.md | 45 +- 10 files changed, 1101 insertions(+), 48 deletions(-) create mode 100644 examples/repl-bench/fixtures/repl-sidekick-markdown.md create mode 100644 examples/repl-bench/journeys/repl-markdown.test.md create mode 100644 packages/cli/src/repl/markdown.ts diff --git a/examples/repl-bench/fixtures/repl-sidekick-markdown.md b/examples/repl-bench/fixtures/repl-sidekick-markdown.md new file mode 100644 index 000000000..59a4afe3f --- /dev/null +++ b/examples/repl-bench/fixtures/repl-sidekick-markdown.md @@ -0,0 +1,70 @@ + + + +```xmd +Scripted Sidekick ready. +``` + +{ready} + + +{?context}The person says: + +Show the Markdown fixture. + + + +``````xmd + +# Sidekick fixture heading + +**sidekick strong** plain +*sidekick slant* plain +`sidekick code` plain +[sidekick fixture label](https://example.test/sidekick-target) plain + +- sidekick first item +- sidekick second item + +```text + sidekick fence indent + +# sidekick fence *literal* +``` +Sidekick fixture end. + + +`````xmd +# Entry fixture heading + +**entry strong** plain +*entry slant* plain +`entry code` plain +[entry fixture label](https://example.test/entry-target) plain +Entry prose keeps going long enough to wrap inside the wide centre pane, so its **entry wrapped strong** run lands after a measured break. + +1. entry first step +2. entry second step + +```text + entry fence indent + +# entry fence *literal* +``` +Entry fixture end. +````` + +{entry} + +`````` + +{submission} + + + + +```xmd +Markdown fixture receipt read. +``` + +{done} diff --git a/examples/repl-bench/journeys/repl-markdown.test.md b/examples/repl-bench/journeys/repl-markdown.test.md new file mode 100644 index 000000000..8d5ac2c40 --- /dev/null +++ b/examples/repl-bench/journeys/repl-markdown.test.md @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/cli/src/repl/application.ts b/packages/cli/src/repl/application.ts index 59a7b83b0..ec4d0eadb 100644 --- a/packages/cli/src/repl/application.ts +++ b/packages/cli/src/repl/application.ts @@ -121,7 +121,9 @@ import type { SidekickFeedback } from "./sidekick/model.ts"; import { inertCommandText } from "./command-output.ts"; import type { ReplCommandOutput } from "./command-output.ts"; import type { ReplReading } from "./source-reading.ts"; -import { readingRuns, fitPlain } from "./fitting.ts"; +import { readingRuns, fitPlain, slicedRuns } from "./fitting.ts"; +import { markdownLines } from "./markdown.ts"; +import type { ReplMarkdownLine } from "./markdown.ts"; import type { ReplPlainFitStore } from "./fitting.ts"; import type { ReplRenderer } from "./renderer.ts"; import type { Operation } from "effection"; @@ -4079,6 +4081,12 @@ type ReplChatComposed = /** The origin drawn over the first four cells of its first row, where marked. */ readonly mark?: ReplOriginMark; readonly action?: { readonly [name: string]: Json }; + /** + * The logical lines a written body is drawn as, with its Markdown runs. + * They join with line breaks to exactly `text`; without them every line + * is drawn in the row's own role. + */ + readonly lines?: readonly ReplMarkdownLine[]; } | { readonly kind: "control"; @@ -4168,9 +4176,10 @@ function sidekickComposedRows( }; if (item.kind === "person") { items.push( - text( + chatBody( `sidekick:${item.key}`, - ` ${item.origin?.kind === "todo" ? "TODO change" : item.origin?.kind === "acp" ? "ACP (" + item.origin.attachment + ")" : "you"}: ${item.text}`, + ` ${item.origin?.kind === "todo" ? "TODO change" : item.origin?.kind === "acp" ? "ACP (" + item.origin.attachment + ")" : "you"}: `, + item.text, styleOf("source"), ), ); @@ -4186,11 +4195,12 @@ function sidekickComposedRows( // nothing saved still said this, so it stays, said as the attempt it is // rather than as an answer or a failure anybody recorded. items.push( - text( + chatBody( `sidekick:${item.key}`, item.incomplete === true - ? ` ${reading.agent} (unfinished): ${item.text}` - : ` ${reading.agent} (preview): ${item.text}`, + ? ` ${reading.agent} (unfinished): ` + : ` ${reading.agent} (preview): `, + item.text, item.incomplete === true ? styleOf("failed-outcome") : styleOf("waiting"), ), ); @@ -4232,7 +4242,7 @@ function sidekickComposedRows( // What that turn had actually said, as the literal Output its saved // source projects. Said after the reason, because the reason is why // there is no more of it. - items.push(text(`sidekick:${item.key}:said`, ` ${item.text}`, styleOf("source"))); + items.push(chatBody(`sidekick:${item.key}:said`, " ", item.text, styleOf("source"))); } if (asked !== undefined && reading.current) { items.push( @@ -4260,7 +4270,7 @@ function sidekickComposedRows( if (item.hasOutput) { // And what it had already rendered, after the reason, because the // reason is why there is no more of it. - items.push(text(`sidekick:${item.key}:said`, ` ${item.text}`, styleOf("output"))); + items.push(chatBody(`sidekick:${item.key}:said`, " ", item.text, styleOf("output"))); } metadata(); continue; @@ -4275,7 +4285,9 @@ function sidekickComposedRows( metadata(); continue; } - items.push(text(`sidekick:${item.key}`, ` ${reading.agent}: ${item.text}`, styleOf("output"))); + items.push( + chatBody(`sidekick:${item.key}`, ` ${reading.agent}: `, item.text, styleOf("output")), + ); metadata(); } if (reading.savedRecovery !== undefined) { @@ -4304,16 +4316,58 @@ function sidekickComposedRows( * that row — a description, a reveal, a test — still finds it. The rest are * derived display rows under it, and are not messages, turns or records. */ -function chatLinesOf( - key: string, - text: string, -): readonly { readonly key: string; readonly text: string }[] { - return text.split("\n").map((own, offset) => ({ - key: offset === 0 ? key : `${key}::${offset}`, - text: own, +function chatLinesOf(one: Extract): readonly ReplChatLine[] { + const shown = + one.lines ?? + one.text + .split("\n") + .map((text) => ({ text, runs: tokenRuns([{ text, token: one.style.role }]) })); + return shown.map((own, offset) => ({ + key: offset === 0 ? one.key : `${one.key}::${offset}`, + text: own.text, + runs: own.runs, })); } +interface ReplChatLine { + readonly key: string; + readonly text: string; + readonly runs: readonly ReplTokenRun[]; +} + +/** + * A written body behind its lead, as the Markdown it was written in. + * + * The body is formatted before anything is put in front of it, so a heading or + * a fence can begin on the first line. The lead goes before the first line and + * the gutter before every line, both in the row's own role. + */ +function chatBody( + key: string, + lead: string, + body: string, + style: ReplRowStyle, + gutter = "", + marked: { + readonly mark?: ReplOriginMark; + readonly action?: { readonly [name: string]: Json }; + } = {}, +): ReplChatComposed { + const lines = markdownLines(body, style.role).map((one, at) => { + const before = at === 0 ? `${gutter}${lead}` : gutter; + const runs = tokenRuns([{ text: before, token: style.role }, ...one.runs]); + return Object.freeze({ text: `${before}${one.text}`, runs }); + }); + return Object.freeze({ + kind: "text" as const, + key, + text: lines.map((one) => one.text).join("\n"), + style, + lines: Object.freeze(lines), + ...marked, + }); +} + /** * Every readable line of the Sidekick's reading, by the key that owns it. * @@ -4323,9 +4377,9 @@ function chatLinesOf( */ export function sidekickChatLines( reading: ReplSidekickReading | undefined, -): readonly { readonly key: string; readonly text: string }[] { +): readonly ReplChatLine[] { return sidekickComposedRows(reading, undefined, true).flatMap((one) => - one.kind === "text" ? chatLinesOf(one.key, one.text) : [], + one.kind === "text" ? chatLinesOf(one) : [], ); } @@ -4342,6 +4396,8 @@ type ReplChatPreparedRow = readonly kind: "text"; readonly key: string; readonly label: string; + /** What each part of `label` is. Concatenates to exactly `label`. */ + readonly runs: readonly ReplTokenRun[]; readonly item: Extract; readonly first: boolean; }; @@ -4367,22 +4423,25 @@ function chatSequence( rows.push(one); continue; } - for (const own of chatLinesOf(one.key, one.text)) { + for (const own of chatLinesOf(one)) { const pieces = cuts.get(own.key); if (pieces === undefined) { rows.push({ kind: "text", key: own.key, label: own.text, + runs: own.runs, item: one, first: own.key === one.key, }); } else { for (const piece of pieces) { + const indent = " ".repeat(piece.indent); rows.push({ kind: "text", key: piece.key, - label: `${" ".repeat(piece.indent)}${piece.text}`, + label: `${indent}${piece.text}`, + runs: tokenRuns([{ text: indent, token: one.style.role }, ...piece.runs]), item: one, first: own.key === one.key && !piece.continuation, }); @@ -4402,13 +4461,17 @@ function materializeChatRow(one: ReplChatPreparedRow, focused: string | undefine } const { action, mark } = one.item; if (one.first && action !== undefined && mark !== undefined) { - const label = mark.text + one.label.slice(CONTROL_ROOM.length + MARKER_ROOM.length); + const behind = CONTROL_ROOM.length + MARKER_ROOM.length; + const label = mark.text + one.label.slice(behind); return row(one.key, label, action, one.item.style, { here: focused, - runs: markedRuns(mark, label, one.item.style.role), + runs: tokenRuns([ + { text: mark.text, token: mark.role }, + ...slicedRuns(one.runs, behind, one.label.length), + ]), }); } - return chatRow(one.key, one.label, one.item, one.first); + return chatRow(one.key, one.label, one.runs, one.item, one.first); } function chatWindow(view: ReplView, context: ReplPresentationContext): readonly Described[] { @@ -4548,9 +4611,7 @@ export function createChatPreparationStore(cuts: ReplPlainFitStore): ReplChatPre style: styleOf("metadata"), }, ]; - const lines = composed.flatMap((one) => - one.kind === "text" ? chatLinesOf(one.key, one.text) : [], - ); + const lines = composed.flatMap((one) => (one.kind === "text" ? chatLinesOf(one) : [])); // Prune before suspension too: a refused or cancelled fit owns no old candidates. cuts.settle( lines.map((one) => one.text), @@ -4586,13 +4647,14 @@ export function createChatPreparationStore(cuts: ReplPlainFitStore): ReplChatPre function chatRow( key: string, label: string, + runs: readonly ReplTokenRun[], one: { readonly style: ReplRowStyle; readonly mark?: ReplOriginMark }, first: boolean, ): Described { const mark = one.mark; const room = CONTROL_ROOM + MARKER_ROOM; if (!first || mark === undefined || !label.startsWith(room)) { - return line(key, label, one.style); + return line(key, label, one.style, runs); } const drawn = mark.text + label.slice(room.length); return line( @@ -4601,7 +4663,8 @@ function chatRow( one.style, tokenRuns([ { text: CONTROL_ROOM, token: one.style.role }, - ...markedRuns(mark, drawn, one.style.role), + { text: mark.text, token: mark.role }, + ...slicedRuns(runs, room.length, label.length), ]), ); } @@ -12462,14 +12525,15 @@ function workspaceChatComposed( const key = `sidekick:${item.key}`; if (item.kind === "person") { items.push( - text( + chatBody( key, + "", item.text, styleOf("source", { selected: staging.inspection?.kind === "person" && staging.inspection.key === item.key, }), - originMark(item.origin), - inspectionAction("person", item.key), + `${CONTROL_ROOM}${MARKER_ROOM}`, + { mark: originMark(item.origin), action: inspectionAction("person", item.key) }, ), ); } else if (item.kind === "preview") { @@ -12477,15 +12541,16 @@ function workspaceChatComposed( // run and no turn is acknowledged, so this is not a reply yet — and a // row that differed from one only by its colour would tell a reader // nothing they could read. `(unfinished)` below is the other ending. - const output = trimLeadingBlankLines(item.text); items.push( - text( + chatBody( key, item.incomplete === true - ? `${reading.agent} (unfinished): ${output}` - : `${reading.agent} (preview): ${output}`, + ? `${reading.agent} (unfinished): ` + : `${reading.agent} (preview): `, + trimLeadingBlankLines(item.text), item.incomplete === true ? styleOf("failed-outcome") : styleOf("waiting"), - SIDEKICK_MARK, + `${CONTROL_ROOM}${MARKER_ROOM}`, + { mark: SIDEKICK_MARK }, ), ); } else if (item.kind === "saved") { @@ -12549,17 +12614,22 @@ function workspaceChatComposed( } else if (item.hasOutput) { const saved = savedTurns.get(`${item.conversation}:${item.turn}`); items.push( - text( + chatBody( key, + "", trimLeadingBlankLines(item.text), styleOf("output", { selected: staging.inspection?.kind === "exchange" && staging.inspection.key === saved?.key, }), - SIDEKICK_MARK, - item.request !== undefined && saved !== undefined - ? inspectionAction("exchange", saved.key) - : undefined, + `${CONTROL_ROOM}${MARKER_ROOM}`, + { + mark: SIDEKICK_MARK, + action: + item.request !== undefined && saved !== undefined + ? inspectionAction("exchange", saved.key) + : undefined, + }, ), ); } diff --git a/packages/cli/src/repl/fitting.ts b/packages/cli/src/repl/fitting.ts index c6ef19095..d5a555cba 100644 --- a/packages/cli/src/repl/fitting.ts +++ b/packages/cli/src/repl/fitting.ts @@ -1164,7 +1164,7 @@ function row( * value on both of them. A run the slice does not touch is absent rather than * empty, which is what keeps the list concatenating to exactly the row's text. */ -function slicedRuns( +export function slicedRuns( runs: readonly ReplTokenRun[], from: number, to: number, diff --git a/packages/cli/src/repl/markdown.ts b/packages/cli/src/repl/markdown.ts new file mode 100644 index 000000000..ce85894a2 --- /dev/null +++ b/packages/cli/src/repl/markdown.ts @@ -0,0 +1,291 @@ +/** + * Markdown somebody wrote, as the logical lines and styled runs this screen + * draws it with. + * + * Shared by the two readings that show written prose: a Sidekick conversation + * body and an entry's rendered Output. Display only. The string passed in is + * the one every journal, save and raw read keeps; nothing here reaches back + * into it. + * + * Headings, emphasis, list markers, link labels and code are styled runs. + * Fenced code keeps every payload line as it was written, indentation and blank + * lines included, because the source span is what is drawn rather than the + * lexer's normalized text. A construct this does not format — raw HTML, a + * component-like tag, a table, a delimiter that never closed — is drawn as the + * text it is. A link shows its label; its target is never drawn, opened or + * written to the terminal as anything. + * + * Controls are made inert before the lexer sees the text, so a carriage return + * cannot become a line break, and again on every run the walk produces. Line + * breaks are the source's own: one written line is one logical line, and + * wrapping stays with the measured fitting that every reading already uses. + */ + +import { Lexer } from "marked"; +import type { Token } from "marked"; +import { inertCommandText } from "./command-output.ts"; +import { tokenRuns } from "./description.ts"; +import type { ReplTokenRun } from "./description.ts"; +import type { ReplPresentationRole } from "./presentation-style.ts"; + +/** One logical line of formatted text. The runs concatenate to exactly `text`. */ +export interface ReplMarkdownLine { + readonly text: string; + readonly runs: readonly ReplTokenRun[]; +} + +interface Part { + readonly text: string; + readonly token: ReplPresentationRole; +} + +type Line = Part[]; + +/** + * The lines one body is drawn as, with its ordinary text in `role`. + * + * Plain text comes back as one line per written line, each one run in `role`. + */ +export function markdownLines( + source: string, + role: ReplPresentationRole, +): readonly ReplMarkdownLine[] { + const lines = blocks(Lexer.lex(inertCommandText(source)), role, true).map((parts) => { + const runs = tokenRuns( + parts.map((part) => ({ text: inertCommandText(part.text), token: part.token })), + ); + return Object.freeze({ text: runs.map((run) => run.text).join(""), runs }); + }); + return Object.freeze(lines); +} + +/** + * Block tokens as lines, blank lines counted from the newlines between them. + * + * The blank rows between two blocks are the line breaks the source put there + * less the one that ends the earlier block. At the start and end of the + * outermost body every break is a row, as splitting the text on its line breaks + * gives. A nested body leaves its trailing breaks to the container holding it. + */ +function blocks(tokens: readonly Token[], role: ReplPresentationRole, outermost: boolean): Line[] { + const lines: Line[] = []; + let pending = 0; + let any = false; + for (const token of tokens) { + if (token.type === "space") { + pending += breaks(token.raw); + continue; + } + for (let blank = any ? pending - 1 : outermost ? pending : 0; blank > 0; blank -= 1) { + lines.push([]); + } + lines.push(...block(token, role)); + pending = trailing(token.raw); + any = true; + } + if (outermost) { + for (let blank = any ? pending : pending + 1; blank > 0; blank -= 1) { + lines.push([]); + } + } + return lines; +} + +function block(token: Token, role: ReplPresentationRole): Line[] { + switch (token.type) { + case "heading": + return inline(token.tokens ?? [], "source-heading"); + case "paragraph": + case "text": + return "tokens" in token && token.tokens !== undefined + ? inline(token.tokens, role) + : literal(token.raw, role); + case "code": + return code(token.raw, "codeBlockStyle" in token && token.codeBlockStyle === "indented"); + case "list": + return list(itemsOf(token), role); + case "blockquote": + return blocks(token.tokens ?? [], role, false).map((one) => [ + { text: "│ ", token: "punctuation" }, + ...one, + ]); + case "hr": + return literal(token.raw, "punctuation"); + case "checkbox": + return [[{ text: token.raw, token: "punctuation" }]]; + default: + return literal(token.raw, role); + } +} + +/** + * Fenced or indented code, from its source span. + * + * The lexer's text strips the indentation a fence was written at, so the raw + * lines are drawn instead: the fences as punctuation, every line between them + * as code. An unterminated fence holds everything after its opening line. + */ +function code(raw: string, indented: boolean): Line[] { + const written = withoutTrailingBreaks(raw).split("\n"); + if (indented) { + return written.map((one) => [{ text: one, token: "markdown-code" }]); + } + const closed = written.length > 1 && FENCE.test(written[written.length - 1]); + return written.map((one, at) => [ + { + text: one, + token: at === 0 || (closed && at === written.length - 1) ? "punctuation" : "markdown-code", + }, + ]); +} + +const FENCE = /^ {0,3}(?:`{3,}|~{3,})\s*$/; + +interface Item { + readonly raw: string; + readonly tokens: readonly Token[]; +} + +function itemsOf(token: Token): readonly Item[] { + const items: Item[] = []; + for (const one of "items" in token && Array.isArray(token.items) ? token.items : []) { + if (typeof one?.raw === "string" && Array.isArray(one.tokens)) { + items.push({ raw: one.raw, tokens: one.tokens }); + } + } + return items; +} + +/** + * A list's items, each under its marker, with the item's further lines set in + * under the marker's width. A bullet is drawn as `•`; an ordered item keeps the + * number and delimiter it was written with. + */ +function list(items: readonly Item[], role: ReplPresentationRole): Line[] { + const lines: Line[] = []; + let pending = 0; + for (const [at, item] of items.entries()) { + for (let blank = at > 0 ? pending - 1 : 0; blank > 0; blank -= 1) { + lines.push([]); + } + const written = MARKER.exec(item.raw)?.[1] ?? "-"; + const marker = /^\d/.test(written) ? `${written} ` : "• "; + const body = blocks(item.tokens, role, false); + for (const [offset, one] of (body.length === 0 ? [[]] : body).entries()) { + if (offset > 0 && one.length === 0) { + lines.push([]); + continue; + } + lines.push([ + { + text: offset === 0 ? marker : " ".repeat(marker.length), + token: "punctuation", + }, + ...one, + ]); + } + pending = trailing(item.raw); + } + return lines; +} + +const MARKER = /^\s*(\d{1,9}[.)]|[-+*])/; + +/** + * Inline tokens as lines, split where the text itself breaks. + * + * `base` is what plain text in this stretch is. + */ +function inline(tokens: readonly Token[], base: ReplPresentationRole): Line[] { + const parts: Part[] = []; + walk(tokens, base, parts); + const lines: Line[] = [[]]; + for (const part of parts) { + const pieces = part.text.split("\n"); + for (const [at, piece] of pieces.entries()) { + if (at > 0) { + lines.push([]); + } + lines[lines.length - 1].push({ text: piece, token: part.token }); + } + } + // A block's own final line break ends its last line; the blank rows after it + // are counted from the raw text by whoever holds the block. + if (lines.length > 1 && lines[lines.length - 1].every((part) => part.text.length === 0)) { + lines.pop(); + } + return lines; +} + +function walk(tokens: readonly Token[], role: ReplPresentationRole, parts: Part[]): void { + for (const token of tokens) { + switch (token.type) { + case "strong": + case "em": + walk( + token.tokens ?? [], + role === "source-heading" + ? role + : token.type === "strong" + ? "markdown-strong" + : "markdown-em", + parts, + ); + break; + case "link": + if ((token.tokens ?? []).length === 0 || token.text.length === 0) { + parts.push({ text: token.raw, token: role }); + } else { + walk(token.tokens ?? [], "markdown-link", parts); + } + break; + case "codespan": + parts.push({ text: codeSpan(token.raw), token: "markdown-code" }); + break; + case "escape": + parts.push({ text: token.text, token: role }); + break; + case "text": + if ("tokens" in token && token.tokens !== undefined && token.tokens.length > 0) { + walk(token.tokens, role, parts); + } else { + parts.push({ text: token.raw, token: role }); + } + break; + default: + parts.push({ text: token.raw, token: role }); + } + } +} + +/** + * A code span's content from its own source, line breaks kept. + * + * The lexer's text turns a break inside a span into a space, which would join + * two written lines into one. + */ +function codeSpan(raw: string): string { + const fence = /^`+/.exec(raw)?.[0].length ?? 0; + const inner = raw.slice(fence, raw.length - fence); + return inner.length > 2 && inner.startsWith(" ") && inner.endsWith(" ") && inner.trim() !== "" + ? inner.slice(1, -1) + : inner; +} + +function literal(raw: string, token: ReplPresentationRole): Line[] { + return withoutTrailingBreaks(raw) + .split("\n") + .map((one) => [{ text: one, token }]); +} + +function withoutTrailingBreaks(raw: string): string { + return raw.replace(/\n+$/, ""); +} + +function trailing(raw: string): number { + return raw.length - raw.replace(/\n+$/, "").length; +} + +function breaks(raw: string): number { + return raw.split("\n").length - 1; +} diff --git a/packages/cli/src/repl/presentation-style.ts b/packages/cli/src/repl/presentation-style.ts index 404dfc258..664d7a229 100644 --- a/packages/cli/src/repl/presentation-style.ts +++ b/packages/cli/src/repl/presentation-style.ts @@ -29,6 +29,15 @@ export type ReplPresentationRole = | "source" /** A heading written in the source being shown. */ | "source-heading" + /** + * Written Markdown emphasis and a link's label: the row's own colour, with + * the weight, slant or underline the Markdown asked for. + */ + | "markdown-strong" + | "markdown-em" + | "markdown-link" + /** Written Markdown code, inline or fenced. */ + | "markdown-code" /** The characters that open and close a tag: `<`, ``, `/>`. */ | "xmd-delimiter" /** What a tag is called. */ @@ -322,6 +331,7 @@ export const REPL_PALETTE = Object.freeze({ * stated as that flag rather than as an escape this product writes itself. */ export const BOLD = 1; +const ITALIC = 4; const UNDERLINE = 8; /** What one row's text is drawn with. */ @@ -358,7 +368,7 @@ export function runStyleOf( ? REPL_PALETTE.heading : row.role === "todo-completed" && !focused ? REPL_PALETTE.historical - : colourOf(role, row.inspected), + : colourOf(INHERITS_ROW_COLOUR.has(role) ? row.role : role, row.inspected), attrs: attrsOf(role) | (row.role === "todo-completed" ? 64 | (focused ? 0 : 2) : 0) | @@ -366,6 +376,13 @@ export function runStyleOf( }); } +/** Roles that say how text is written rather than what it is. */ +const INHERITS_ROW_COLOUR: ReadonlySet = new Set([ + "markdown-strong", + "markdown-em", + "markdown-link", +]); + /** * What one row's whole measured width is painted with, or none where the pane it * sits in supplies it. @@ -420,6 +437,8 @@ function colourOf(role: ReplPresentationRole, inspected: boolean): number { case "todo-completed": return REPL_PALETTE.historical; case "todo-em": + case "markdown-strong": + case "markdown-em": case "output": case "field-value": return REPL_PALETTE.output; @@ -427,6 +446,7 @@ function colourOf(role: ReplPresentationRole, inspected: boolean): number { case "drawer-title": case "action": case "navigate": + case "markdown-link": return REPL_PALETTE.heading; case "field-label": case "json-null": @@ -442,6 +462,7 @@ function colourOf(role: ReplPresentationRole, inspected: boolean): number { case "xmd-attribute": return REPL_PALETTE.attribute; case "xmd-value": + case "markdown-code": return REPL_PALETTE.quoted; case "reference-brace": return REPL_PALETTE.brace; @@ -532,7 +553,10 @@ function colourOf(role: ReplPresentationRole, inspected: boolean): number { function attrsOf(role: ReplPresentationRole): number { switch (role) { case "todo-em": - return 4; + case "markdown-em": + return ITALIC; + case "markdown-link": + return UNDERLINE; case "todo-completed": return 64 | 2; case "pane-heading": @@ -540,6 +564,7 @@ function attrsOf(role: ReplPresentationRole): number { case "question-title": case "field-label": case "source-heading": + case "markdown-strong": return BOLD; default: return 0; diff --git a/packages/cli/src/repl/source-reading.ts b/packages/cli/src/repl/source-reading.ts index c0e3db7f1..10ac74d78 100644 --- a/packages/cli/src/repl/source-reading.ts +++ b/packages/cli/src/repl/source-reading.ts @@ -49,6 +49,7 @@ import { tokenRuns } from "./description.ts"; import type { ReplTokenRun } from "./description.ts"; import { sourceRuns, trimLeadingBlankLines } from "./presentation-text.ts"; import { inertCommandText } from "./command-output.ts"; +import { markdownLines } from "./markdown.ts"; import type { ReplCommandChunk } from "./command-output.ts"; /** What this terminal draws for each phase, glyph and word together. */ @@ -227,7 +228,11 @@ function outputSection(request: ReplReadingRequest): ReplReadingSection { return Object.freeze({ caption: "Output · live", captionStyle: styleOf("waiting", { inspected }), - lines: plain(trimLeadingBlankLines(live), "output:live", styleOf("output", { inspected })), + lines: written( + trimLeadingBlankLines(live), + "output:live", + styleOf("output", { inspected }), + ), }); } return Object.freeze({ @@ -240,7 +245,7 @@ function outputSection(request: ReplReadingRequest): ReplReadingSection { return Object.freeze({ caption: "Output", captionStyle: styleOf("pane-heading", { inspected }), - lines: plain( + lines: written( trimLeadingBlankLines(terminal.output), "output", styleOf("output", { inspected }), @@ -279,6 +284,27 @@ function outputSection(request: ReplReadingRequest): ReplReadingSection { }); } +/** + * Rendered Output as the Markdown it was written in, in lines nothing has been + * observed in. The live text and the retained result take the same path, so a + * settled reading draws what its last live frame drew. + */ +function written(text: string, prefix: string, style: ReplRowStyle): readonly ReplReadingLine[] { + return Object.freeze( + markdownLines(text, style.role).map((one, index) => + Object.freeze({ + key: `${prefix}:${index}`, + text: one.text, + runs: one.runs, + rail: "rail-pending" as const, + depth: 0, + badge: undefined, + style, + }), + ), + ); +} + /** Text as lines nothing has been observed in. */ function plain(text: string, prefix: string, style: ReplRowStyle): readonly ReplReadingLine[] { return Object.freeze( diff --git a/packages/cli/tests/repl-sidekick-journey.test.ts b/packages/cli/tests/repl-sidekick-journey.test.ts index 1a678aad1..f60f2c98a 100644 --- a/packages/cli/tests/repl-sidekick-journey.test.ts +++ b/packages/cli/tests/repl-sidekick-journey.test.ts @@ -94,7 +94,10 @@ import { settledReading } from "./support/mounted-history.ts"; import type { MountedRepl } from "./support/mounted-repl.ts"; import { useReplPage } from "./support/repl-page.ts"; import type { ReplPage, ScreenReading } from "./support/repl-page.ts"; +import { REPL_PALETTE } from "../src/repl/presentation-style.ts"; import { + closeDrawer, + COMPOSER, COMPOSER_VALUE, composerHolds, draftHolds, @@ -5205,3 +5208,415 @@ describe("1183 — a follow-up sent during live automatic feedback", () => { expect(known.recoveryPending).toBe(false); }); }); + +/** + * #1342 — written Markdown in the chat and in an entry's Output. + * + * One real exchange: the scripted reply streams its Output in three held + * pieces and then submits a real entry whose document is Markdown. Both bodies + * are read off the mounted terminal's own cells at the wide and narrow sizes, + * after a cold reopen, and against the strings their existing readers retain. + * Each formatted word is followed by `plain`, so its style is compared with the + * ordinary cell beside it, and each is spelled so that only the formatted + * reading contains it: Source, the raw inspection and the chat's copy of the + * entry's Output all keep the punctuation around it. + */ +describe("1342 — written Markdown in the chat and in entry Output", () => { + const WIDE_SIZE = { columns: 160, rows: 36 }; + const NARROW_SIZE = { columns: 72, rows: 20 }; + const ENTRY_MARKDOWN = [ + "# Entrymark heading", + "", + "**entrybold** plain", + "*entryslant* plain", + "`entrycode` plain", + "[entrylabel](https://example.test/entry-target) plain", + "Entry prose keeps going past the edge of the reading so that the measured fit wraps it, with **entrytail** plain after the wrap and 界 é at the end.", + "", + "1. entry first", + "2. entry second", + "", + "```text", + " entryfence indent", + "", + "# entryfence *literal*", + "```", + "entry raw html", + "Entryend marker.", + ].join("\n"); + const CHAT_MARKDOWN = [ + "# Chatmark heading", + "", + "**chatbold** plain", + "*chatslant* plain", + "`chatcode` plain", + "[chatlabel](https://example.test/chat-target) plain", + "chatctl \x1b\x07 done", + "", + "- chat first", + "- chat second", + "", + "```text", + " chatfence indent", + "", + "# chatfence *literal*", + "```", + "Chatend marker.", + ].join("\n"); + const SUBMISSION = [ + '', + "````xmd", + ENTRY_MARKDOWN, + "````", + "", + "{code}", + "", + "", + ].join("\n"); + const REPLY = `\n${CHAT_MARKDOWN}\n\n${SUBMISSION}`; + // Held after an unclosed strong delimiter, and again inside an open fence. + const BOLD_OPEN = REPLY.indexOf("plain"); + const FENCE_OPEN = REPLY.indexOf("\n# chatfence"); + const PIECES = [ + REPLY.slice(0, BOLD_OPEN - 3), + REPLY.slice(BOLD_OPEN - 3, FENCE_OPEN), + REPLY.slice(FENCE_OPEN), + ]; + + /** The cells of the mounted emulator, which a substring search cannot see. */ + function inkAt(page: ReplPage, at: { readonly column: number; readonly row: number }) { + const screen = page.repl.terminal.screen; + if (screen === undefined) { + throw new Error("the mounted terminal has no screen"); + } + return screen.styleAt(at.column, at.row); + } + + /** One match: the cell it starts in, and the offset into its row's text. */ + interface Spot { + readonly column: number; + readonly row: number; + readonly offset: number; + } + + /** + * The cell an offset into a row's text was drawn in. + * + * A wide glyph is one code unit over two cells and a combining sequence + * several units in one, so the two differ on a row holding either. + */ + function columnOf(page: ReplPage, row: number, offset: number): number { + const cells = page.repl.terminal.screen?.cells()[row] ?? []; + let at = 0; + for (const [column, cell] of cells.entries()) { + if (cell === "") { + continue; + } + if (at >= offset) { + return column; + } + at += cell.length; + } + return cells.length; + } + + /** The text from one cell onward on a row, as the emulator holds it. */ + function fromColumn(page: ReplPage, row: number, column: number): string { + return (page.repl.terminal.screen?.cells()[row] ?? []).slice(column).join(""); + } + + /** Where this text starts on the screen, wherever its first cell holds. */ + function cellsOf( + page: ReplPage, + reading: ScreenReading, + text: string, + holds: (style: ReturnType, row: string, column: number) => boolean = () => true, + ): Spot[] { + const found: Spot[] = []; + for (const [row, line] of reading.rows.entries()) { + for (let at = line.indexOf(text); at !== -1; at = line.indexOf(text, at + 1)) { + const column = columnOf(page, row, at); + if (holds(inkAt(page, { column, row }), line, at)) { + found.push({ column, row, offset: at }); + } + } + } + return found; + } + + /** The one place this text is drawn without the Markdown written around it. */ + function formatted(page: ReplPage, reading: ScreenReading, text: string): Spot { + const found = cellsOf(page, reading, text, (_style, line, at) => { + const before = line.slice(Math.max(0, at - 2), at); + const after = line[at + text.length] ?? ""; + return !/[*`[_]$/.test(before) && before !== "# " && !/^[*`\]_]/.test(after); + }); + if (found.length !== 1) { + throw new Error(`${found.length} formatted ${text}:\n${reading.rows.join("\n")}`); + } + return found[0]; + } + + /** The style of the `plain` cell that follows a formatted word on its row. */ + function plainAfter(page: ReplPage, reading: ScreenReading, at: Spot) { + const offset = reading.rows[at.row].indexOf(" plain", at.offset) + 1; + expect(offset).toBeGreaterThan(at.offset); + return inkAt(page, { column: columnOf(page, at.row, offset), row: at.row }); + } + + /** Wheel one reading until this holds, through the reading's own scroll. */ + function* reveal( + page: ReplPage, + what: string, + holds: (reading: ScreenReading) => boolean, + at: (reading: ScreenReading) => { readonly column: number; readonly row: number }, + direction: "up" | "down", + ): Operation { + for (let step = 0; step < 40 && !holds(page.screen()); step += 1) { + const index = page.screen().index; + yield* page.wheel(direction, at(page.screen())); + yield* page.until(what, (one) => one.index > index || holds(one)); + } + return yield* page.until(what, holds); + } + + /** Where the chat scrolls: above the composer, which stays put. */ + function inChat(reading: ScreenReading): { readonly column: number; readonly row: number } { + const composer = reading.locate(COMPOSER); + return { column: composer.column, row: composer.row - 3 }; + } + + /** One formatted body, read off the cells: `word` is `chat` or `entry`. */ + function* readsFormatted(page: ReplPage, word: "chat" | "entry"): Operation { + const reading = page.screen(); + const heading = formatted(page, reading, `${word === "chat" ? "Chat" : "Entry"}mark heading`); + expect(inkAt(page, heading).attrs).toContain(1); + expect(inkAt(page, heading).foreground).toBe(REPL_PALETTE.sourceHeading); + + const bold = formatted(page, reading, `${word}bold`); + expect(inkAt(page, bold).attrs).toContain(1); + expect(plainAfter(page, reading, bold).attrs).not.toContain(1); + expect(inkAt(page, bold).foreground).toBe(plainAfter(page, reading, bold).foreground); + + const slant = formatted(page, reading, `${word}slant`); + expect(inkAt(page, slant).attrs).toContain(3); + expect(plainAfter(page, reading, slant).attrs).not.toContain(3); + + const code = formatted(page, reading, `${word}code`); + expect(inkAt(page, code).foreground).toBe(REPL_PALETTE.quoted); + expect(plainAfter(page, reading, code).foreground).not.toBe(REPL_PALETTE.quoted); + + // A label and nothing of its target, and no action of its own: the row is + // read, not activated. + const label = formatted(page, reading, `${word}label`); + expect(inkAt(page, label).attrs).toContain(4); + expect(plainAfter(page, reading, label).attrs).not.toContain(4); + expect(reading.rows[label.row]).not.toContain(`${word}-target`); + expect(reading.rows[label.row]).not.toContain("]("); + + // The fence: its payload literal and in code, its indentation in place, + // its blank line a row and the Markdown inside it unformatted. + const indent = cellsOf( + page, + reading, + `${word}fence indent`, + (style) => style.foreground === REPL_PALETTE.quoted, + ); + expect(indent).toHaveLength(1); + const payload = indent[0]; + expect(fromColumn(page, payload.row, payload.column - 2).startsWith(" ")).toBe(true); + expect(fromColumn(page, payload.row - 1, payload.column - 2)).toMatch(/^```text\s*(│|$)/); + expect(inkAt(page, { column: payload.column - 2, row: payload.row - 1 }).foreground).toBe( + REPL_PALETTE.punctuation, + ); + expect( + fromColumn(page, payload.row + 1, payload.column - 2) + .slice(0, 20) + .trim(), + ).toBe(""); + expect( + fromColumn(page, payload.row + 2, payload.column - 2).startsWith(`# ${word}fence *literal*`), + ).toBe(true); + expect(inkAt(page, { column: payload.column - 2, row: payload.row + 2 }).foreground).toBe( + REPL_PALETTE.quoted, + ); + } + + it("1342 MD1: both bodies format at wide and narrow sizes, stream, reopen and keep their text", function* () { + const host = yield* useMountedHost(); + let location = ""; + let execution = ""; + yield* scoped(function* (): Operation { + const page = yield* useReplPage({ host, size: WIDE_SIZE }); + const repl = page.repl; + repl.fake.script({ deltas: PIECES, holdsEachPiece: true }); + repl.fake.script({ reply: "Receipt read.\n" }); + yield* sendMessage(page, "Show the Markdown fixture."); + + // A prefix ending inside a strong delimiter reads as what it literally + // is, beside a heading already formatted on the first body row. + yield* repl.fake.streamingTurns(1); + const first = yield* page.until("the first preview", (one) => + one.shows(`${MOUNTED_AGENT} (preview): Chatmark heading`), + ); + const previewHeading = formatted(page, first, "Chatmark heading"); + expect(inkAt(page, previewHeading).attrs).toContain(1); + expect(first.shows("**chatbold")).toBe(true); + + // The delimiter closes in the next piece and the same item converges on + // the formatted run. The fence it ends inside is not Output yet, so the + // preview withholds it rather than showing a partial block. + repl.fake.releaseDeltas(); + yield* repl.fake.streamingTurns(1); + const closing = yield* page.until("the closed delimiter in the preview", (one) => + one.shows("chatbold plain"), + ); + expect(inkAt(page, formatted(page, closing, "chatbold")).attrs).toContain(1); + expect(closing.shows("**chatbold")).toBe(false); + expect(closing.shows(`${MOUNTED_AGENT} (preview)`)).toBe(true); + expect(closing.shows("chatfence")).toBe(false); + + repl.fake.releaseDeltas(); + yield* page.until("the receipt", (one) => saidBySidekick(one, "Receipt read.")); + yield* page.until("the pane at rest", sidekickIdle); + expect(page.screen().shows("(preview)")).toBe(false); + + // The retained strings keep every byte of the Markdown, targets included. + const read = yield* settledReading(repl); + execution = read.execution; + expect(read.model.entries.map((entry) => entry.terminal?.output)).toEqual([ENTRY_MARKDOWN]); + const responses = read.chat.flatMap((record) => + record.kind === "response" && record.output !== undefined ? [record.output] : [], + ); + expect(responses[0]).toContain(CHAT_MARKDOWN); + + // Wide: the entry's Output in the centre, the chat on the right. + yield* readsFormatted(page, "entry"); + // The long line starts on the row after the label, so a bold run past + // its first fitted row was carried onto a continuation. + expect(formatted(page, page.screen(), "entrytail").row).toBeGreaterThan( + formatted(page, page.screen(), "entrylabel").row + 1, + ); + expect(inkAt(page, formatted(page, page.screen(), "entrytail")).attrs).toContain(1); + expect(page.screen().shows("• chat first")).toBe(false); + expect(page.screen().shows("1. entry first")).toBe(true); + expect(page.screen().shows("entry raw html")).toBe(true); + expect(page.screen().shows("Entryend marker.")).toBe(true); + yield* reveal( + page, + "the chat's own heading", + (one) => one.shows("[S] Chatmark heading") && one.shows("Chatend marker."), + inChat, + "up", + ); + yield* readsFormatted(page, "chat"); + expect(page.screen().shows("• chat first")).toBe(true); + expect(page.screen().shows("chatctl \\x1b\\x07 done")).toBe(true); + + // The raw inspection of that exchange is still the Markdown as written. + yield* page.press("[S] Chatmark heading"); + const drawer = yield* page.until("the exchange inspection", (one) => + one.shows("**chatbold** plain"), + ); + expect(drawer.shows("[chatlabel](https://example.test/chat-target) plain")).toBe(true); + expect(drawer.shows("Sidekick · 2 saved turns")).toBe(true); + yield* closeDrawer(page); + + // Narrow: the routed chat, then the Entries reading in the same outlet. + yield* page.resize(NARROW_SIZE); + yield* reveal( + page, + "the narrow chat's heading", + (one) => one.shows("[S] Chatmark heading"), + inChat, + "up", + ); + const narrowHeading = formatted(page, page.screen(), "Chatmark heading"); + expect(inkAt(page, narrowHeading).attrs).toContain(1); + const narrowBold = formatted(page, page.screen(), "chatbold"); + expect(inkAt(page, narrowBold).attrs).toContain(1); + yield* reveal( + page, + "the narrow chat's fence", + (one) => one.shows("# chatfence *literal*") && one.shows("chatfence indent"), + inChat, + "down", + ); + expect( + cellsOf( + page, + page.screen(), + "chatfence indent", + (style) => style.foreground === REPL_PALETTE.quoted, + ), + ).toHaveLength(1); + + yield* page.press("Entries"); + yield* page.until("the narrow Entries catalog", (one) => one.shows("[close]")); + yield* closeDrawer(page); + // The shared catalog and reading scroll together below the selected + // entry's trail, which stays put. + const output = (one: ScreenReading) => ({ + column: 4, + row: one.rows.findIndex((row) => row.includes("› Entry 1")) + 4, + }); + yield* reveal( + page, + "the narrow entry heading", + (one) => one.shows("Entrymark heading") && one.shows("entrylabel plain"), + output, + "down", + ); + const entryLabel = formatted(page, page.screen(), "entrylabel"); + expect(inkAt(page, entryLabel).attrs).toContain(4); + expect(page.screen().rows[entryLabel.row]).not.toContain("entry-target"); + yield* reveal( + page, + "the narrow entry fence", + (one) => one.shows("# entryfence *literal*"), + output, + "down", + ); + const narrowFence = cellsOf( + page, + page.screen(), + "entryfence indent", + (style) => style.foreground === REPL_PALETTE.quoted, + ); + expect(narrowFence).toHaveLength(1); + expect( + page + .screen() + .rows[narrowFence[0].row].slice(narrowFence[0].column - 2, narrowFence[0].column), + ).toBe(" "); + + yield* page.resize(WIDE_SIZE); + page.repl.terminal.end(); + yield* awaited("the first command joined", () => page.repl.outcome() !== undefined); + const result = page.repl.outcome(); + if (result === undefined || !result.ok) { + throw new Error("the first command failed"); + } + location = result.value.location; + }); + + // Cold: the same bodies from what was retained, with no provider turn. + const before = host.fake.prompts.length; + const cold = yield* useReplPage({ host, size: WIDE_SIZE, location }); + yield* cold.until("the reopened entry", (one) => one.shows("Entrymark heading")); + yield* readsFormatted(cold, "entry"); + yield* reveal( + cold, + "the reopened chat's heading", + (one) => one.shows("[S] Chatmark heading") && one.shows("Chatend marker."), + inChat, + "up", + ); + yield* readsFormatted(cold, "chat"); + expect(cold.screen().shows("(preview)")).toBe(false); + expect(host.fake.prompts).toHaveLength(before); + const reopened = yield* settledReading(cold.repl); + expect(reopened.execution).toBe(execution); + expect(reopened.model.entries.map((entry) => entry.terminal?.output)).toEqual([ENTRY_MARKDOWN]); + }); +}); diff --git a/packages/cli/tests/repl-source-reading.test.ts b/packages/cli/tests/repl-source-reading.test.ts index 065c5a4c0..ba83c3fbf 100644 --- a/packages/cli/tests/repl-source-reading.test.ts +++ b/packages/cli/tests/repl-source-reading.test.ts @@ -27,6 +27,8 @@ import { expect } from "@executablemd/test-support/expect"; import { Ok, scoped } from "effection"; import type { Operation, Result } from "effection"; +import { inertCommandText } from "../src/repl/command-output.ts"; +import { markdownLines } from "../src/repl/markdown.ts"; import { entryReading, NO_READING, READING_STATUSES } from "../src/repl/source-reading.ts"; import type { ReplReadingLine } from "../src/repl/source-reading.ts"; import { @@ -1649,3 +1651,74 @@ describe("S8 lines fitted together are cut as each is cut alone", () => { expect(rowsOf(prepared.value)).toEqual(oracle.value); })); }); + +/** + * #1342 — written Markdown as display lines. + * + * Input and output only: the mounted journey in `repl-sidekick-journey.test.ts` + * reads both production surfaces off real terminal cells. These rows hold the + * limits a streamed or arbitrary body reaches and that journey cannot stage + * through a live provider: a fence nobody closed, delimiters nobody closed, raw + * HTML, a carriage return and plain text that must draw exactly as it did. + */ +function markdownShown(source: string): string[] { + return markdownLines(source, "output").map((line) => line.text); +} + +function markdownRoles(source: string): string[][] { + return markdownLines(source, "output").map((line) => + line.runs.map((run) => `${run.token}:${run.text}`), + ); +} + +describe("1342 written Markdown as display lines", () => { + it("draws plain text exactly as its written lines, in the body's own role", function* () { + const plain = "\n\nfirst line\n indented second\n\n\nafter two blank lines\n"; + expect(markdownShown(plain)).toEqual(plain.split("\n")); + expect( + markdownLines(plain, "waiting").every((line) => + line.runs.every((run) => run.token === "waiting"), + ), + ).toBe(true); + expect(markdownShown("")).toEqual([""]); + }); + + it("keeps an unclosed fence's payload literal through the available end", function* () { + expect(markdownRoles("Before\n```ts\n open payload\n\n# still code *here*")).toEqual([ + ["output:Before"], + ["punctuation:```ts"], + ["markdown-code: open payload"], + [], + ["markdown-code:# still code *here*"], + ]); + }); + + it("reads unclosed delimiters, raw HTML and component-like text as written", function* () { + expect(markdownShown("**half bold and `half code")).toEqual(["**half bold and `half code"]); + expect(markdownShown('{said}\nraw')).toEqual([ + "{said}", + 'raw', + ]); + }); + + it("shows a link's label and never its target", function* () { + const lines = markdownLines("See [the label](https://example.test/secret) now", "output"); + expect(lines.map((line) => line.text)).toEqual(["See the label now"]); + expect(lines[0].runs.find((run) => run.token === "markdown-link")?.text).toBe("the label"); + expect(JSON.stringify(lines)).not.toContain("example.test"); + }); + + it("makes controls inert before the lexer reads them", function* () { + const source = "a\rb \x1b]8;;https://x.test\x07link\x1b]8;;\x07 **c\x9b**"; + const lines = markdownShown(source); + expect(lines).toHaveLength(1); + expect(lines[0]).toBe( + inertCommandText("a\rb \x1b]8;;https://x.test\x07link\x1b]8;;\x07 c\x9b"), + ); + expect(lines[0]).not.toMatch(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/); + }); + + it("keeps a code span's line break as a line break", function* () { + expect(markdownRoles("`one\ntwo`")).toEqual([["markdown-code:one"], ["markdown-code:two"]]); + }); +}); diff --git a/specs/repl-spec.md b/specs/repl-spec.md index fdd6f3845..94a2631d4 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -1463,7 +1463,8 @@ text waits until something computes it, an example in a fence is an example, and a prefix that cannot be read as a root shows nothing at all rather than source. Nothing of it has happened — no control has run, no entry has been filled, no turn is acknowledged — and a prefix that happens to read as finished is not -permission to run it. +permission to run it. The preview, the reply and every other conversation body +are drawn as [written Markdown](#written-markdown-in-output-and-in-the-chat). An Output declaration can sit inside control flow or a scoped component. Its text waits for evaluation when an executable ancestor decides whether or how it @@ -2034,7 +2035,8 @@ label becomes `Output`. A root that settled having rendered nothing reads `No rendered output.` and then the outcome it closed with, and a recorded reason beside it. A prefix that retained no output for its entry reads `No entry output recorded at this checkpoint.` — never text borrowed from a later -position or from a run still going. +position or from a run still going. Output text is drawn as +[written Markdown](#written-markdown-in-output-and-in-the-chat). Which of those is shown is decided by what the record says, not by the words in it. A document whose own prose contains `failed` is still output; a root that @@ -2085,6 +2087,45 @@ the producer: nothing is matched by name or by sibling order. Replacing what is displayed rewrites no submitted source and no record. +### Written Markdown in Output and in the chat + +An entry's rendered Output and a Sidekick conversation body are drawn as the +Markdown they were written in, by one display rule. In the chat the rule covers +a person's message and the Sidekick's preview, reply and unfinished attempt. The +speaker, origin, status and gutter in front of a body are not part of it: the +body is formatted first, so a heading or a fence can begin on its first row. + +A heading is drawn as its text in the source-heading style. Strong text is bold, +emphasis is italic and a link is underlined, each in the colour of the text +around it; inline and fenced code take the code colour. An ordered item keeps the +number it was written with, a bullet is drawn as `•`, and an item's further +lines and nested items are set in under its marker. A link shows its label and +nothing of its target: the target is not drawn, cannot be activated, and reaches +the terminal as no hyperlink or other control sequence. + +A fence is drawn line for line. Its delimiter rows stay, as punctuation, and its +payload keeps every indentation, blank line and line break, with any Markdown +inside it left unformatted. A fence that has not closed holds everything after +its opening row, and indented code is drawn the same way. Raw HTML, a +component-like tag, a table, an image and a delimiter that never closed are drawn +as the text they are. Each written line stays one logical line, so text with no +Markdown in it is drawn line for line in the body's own style, and the measured +wrapping in [Everything on this screen was measured](#everything-on-this-screen-was-measured) +fits every row. + +The command-text conversion above makes every displayed run of both bodies inert +before the Markdown is read, so a carriage return cannot become a line break and +a control sequence stays readable text. + +Formatting changes display copies only. Retained Output, saved messages and +replies, their raw inspection and copy routes, and every read keep the Markdown +exactly as written, link targets included. Live Output and the retained result +that replaces it are drawn by the same rule, as are a preview and the reply it +becomes, so settling and a cold reopen show what the last live frame showed. +Source, command stdout and stderr, recorded feedback, title and headline +previews, an entry's work rows in the chat, the Draft and the composer keep their +own presentation. + ## Everything on this screen was measured Measurement and committed presentation both omit retired window controls; their From 96f065c46b23a6db802c526e1a0fea29785ac533 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 21:47:03 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Keep=20fence=20payload=20and?= =?UTF-8?q?=20written=20blank-line=20spaces=20in=20Markdown=20display=20(#?= =?UTF-8?q?1342)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A fence-like line closes only a fence opened with the same character and no longer run; a shorter or different run stays code. Lines written between blocks are drawn as written, so a whitespace-only line keeps its spaces. The spec states that formatting draws exactly the body its owner supplies. --- packages/cli/src/repl/markdown.ts | 54 ++++++++++++------- .../cli/tests/repl-source-reading.test.ts | 45 ++++++++++++++++ specs/repl-spec.md | 16 +++--- 3 files changed, 89 insertions(+), 26 deletions(-) diff --git a/packages/cli/src/repl/markdown.ts b/packages/cli/src/repl/markdown.ts index ce85894a2..ff702af53 100644 --- a/packages/cli/src/repl/markdown.ts +++ b/packages/cli/src/repl/markdown.ts @@ -60,33 +60,37 @@ export function markdownLines( } /** - * Block tokens as lines, blank lines counted from the newlines between them. + * Block tokens as lines, with the lines written between them. * - * The blank rows between two blocks are the line breaks the source put there - * less the one that ends the earlier block. At the start and end of the - * outermost body every break is a row, as splitting the text on its line breaks - * gives. A nested body leaves its trailing breaks to the container holding it. + * The rows between two blocks are the lines the source wrote there, spaces + * included: the text after the earlier block's last line break and before the + * next block. At the start and end of the outermost body every one of those + * lines is a row, as splitting the text on its line breaks gives. A nested body + * leaves its leading and trailing lines to the container holding it. */ function blocks(tokens: readonly Token[], role: ReplPresentationRole, outermost: boolean): Line[] { const lines: Line[] = []; - let pending = 0; + let gap = ""; let any = false; + const between = (written: readonly string[]) => { + for (const one of written) { + lines.push(one.length === 0 ? [] : [{ text: one, token: role }]); + } + }; for (const token of tokens) { if (token.type === "space") { - pending += breaks(token.raw); + gap += token.raw; continue; } - for (let blank = any ? pending - 1 : outermost ? pending : 0; blank > 0; blank -= 1) { - lines.push([]); - } + const written = gap.split("\n"); + between(any ? written.slice(1, -1) : outermost ? written.slice(0, -1) : []); lines.push(...block(token, role)); - pending = trailing(token.raw); + gap = token.raw.slice(withoutTrailingBreaks(token.raw).length); any = true; } if (outermost) { - for (let blank = any ? pending : pending + 1; blank > 0; blank -= 1) { - lines.push([]); - } + const written = gap.split("\n"); + between(any ? written.slice(1) : written); } return lines; } @@ -130,7 +134,7 @@ function code(raw: string, indented: boolean): Line[] { if (indented) { return written.map((one) => [{ text: one, token: "markdown-code" }]); } - const closed = written.length > 1 && FENCE.test(written[written.length - 1]); + const closed = written.length > 1 && closes(written[0], written[written.length - 1]); return written.map((one, at) => [ { text: one, @@ -139,7 +143,21 @@ function code(raw: string, indented: boolean): Line[] { ]); } -const FENCE = /^ {0,3}(?:`{3,}|~{3,})\s*$/; +/** + * Whether a line closes the fence this opening line began: the same character, + * at least as many of it, and nothing after them but spaces. A shorter run or + * the other character is payload. + */ +function closes(opening: string, line: string): boolean { + const opened = /^ {0,3}(`{3,}|~{3,})/.exec(opening)?.[1]; + const closing = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line)?.[1]; + return ( + opened !== undefined && + closing !== undefined && + closing[0] === opened[0] && + closing.length >= opened.length + ); +} interface Item { readonly raw: string; @@ -285,7 +303,3 @@ function withoutTrailingBreaks(raw: string): string { function trailing(raw: string): number { return raw.length - raw.replace(/\n+$/, "").length; } - -function breaks(raw: string): number { - return raw.split("\n").length - 1; -} diff --git a/packages/cli/tests/repl-source-reading.test.ts b/packages/cli/tests/repl-source-reading.test.ts index ba83c3fbf..b9b98a653 100644 --- a/packages/cli/tests/repl-source-reading.test.ts +++ b/packages/cli/tests/repl-source-reading.test.ts @@ -1683,6 +1683,35 @@ describe("1342 written Markdown as display lines", () => { expect(markdownShown("")).toEqual([""]); }); + it("keeps the written spaces of a whitespace-only line, which still fits as one row", () => + withRenderer(function* (renderer) { + expect( + markdownLines("foo\n \nbar", "output").map((line) => ({ + text: line.text, + runs: line.runs.map((run) => run.token), + })), + ).toEqual([ + { text: "foo", runs: ["output"] }, + { text: " ", runs: ["output"] }, + { text: "bar", runs: ["output"] }, + ]); + expect(markdownShown("foo\n\n \n\nbar\n ")).toEqual(["foo", "", " ", "", "bar", " "]); + const lines = entryReading({ + entry: entryOf('', { + terminal: settled("ok", "foo\n \nbar"), + settled: true, + }), + lifecycle: NO_LIFECYCLE, + live: "", + inspected: false, + }).output.lines; + const prepared = yield* prepareReading(renderer, WIDE, lines, 100); + if (!prepared.ok) { + throw prepared.error; + } + expect(prepared.value.rows.map((one) => one.text)).toEqual(["foo", " ", "bar"]); + })); + it("keeps an unclosed fence's payload literal through the available end", function* () { expect(markdownRoles("Before\n```ts\n open payload\n\n# still code *here*")).toEqual([ ["output:Before"], @@ -1691,6 +1720,22 @@ describe("1342 written Markdown as display lines", () => { [], ["markdown-code:# still code *here*"], ]); + // A shorter run of the opener's character cannot close it, so it is payload. + expect(markdownRoles("````text\n tail\n```")).toEqual([ + ["punctuation:````text"], + ["markdown-code: tail"], + ["markdown-code:```"], + ]); + expect(markdownRoles("~~~\nx\n```")).toEqual([ + ["punctuation:~~~"], + ["markdown-code:x"], + ["markdown-code:```"], + ]); + expect(markdownRoles("````text\nx\n````` ")).toEqual([ + ["punctuation:````text"], + ["markdown-code:x"], + ["punctuation:````` "], + ]); }); it("reads unclosed delimiters, raw HTML and component-like text as written", function* () { diff --git a/specs/repl-spec.md b/specs/repl-spec.md index 94a2631d4..96c692419 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -2117,12 +2117,16 @@ The command-text conversion above makes every displayed run of both bodies inert before the Markdown is read, so a carriage return cannot become a line break and a control sequence stays readable text. -Formatting changes display copies only. Retained Output, saved messages and -replies, their raw inspection and copy routes, and every read keep the Markdown -exactly as written, link targets included. Live Output and the retained result -that replaces it are drawn by the same rule, as are a preview and the reply it -becomes, so settling and a cold reopen show what the last live frame showed. -Source, command stdout and stderr, recorded feedback, title and headline +Formatting changes display copies only. It draws exactly the body its owner +supplies — the selected live or retained Output, the admitted preview, the +evaluated reply, the saved message — and adds or removes nothing of it. Retained +Output, saved messages and replies, their raw inspection and copy routes, and +every read keep that body exactly as it was supplied, link targets included. +Evaluation can make a reply differ from the source the agent wrote, and +settlement can supply computed text the preview never held; each stage is +drawn from its own body, and the same body is drawn the same way at every stage. +A cold reopen draws the retained body. Source, command stdout and stderr, +recorded feedback, title and headline previews, an entry's work rows in the chat, the Draft and the composer keep their own presentation.