markdansi 0.1.7 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 ![npm](https://img.shields.io/npm/v/markdansi) ![license MIT](https://img.shields.io/badge/license-MIT-blue.svg) ![node >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen) ![tests vitest](https://img.shields.io/badge/tests-vitest-blue?logo=vitest)
 
-Tiny, dependency-light Markdown → ANSI renderer and CLI for modern Node (>=22). Focuses on readable terminal output with sensible wrapping, GFM support (tables, task lists, strikethrough), optional OSC‑8 hyperlinks, and zero built‑in syntax highlighting (pluggable hook). Includes live in-place terminal rendering for streaming updates (`createLiveRenderer`). Written in TypeScript, ships ESM.
+Tiny, dependency-light Markdown → ANSI renderer and CLI for modern Node (>=22). Focuses on readable terminal output with sensible wrapping, GFM support (tables, task lists, strikethrough), optional OSC‑8 hyperlinks, and zero built‑in syntax highlighting (pluggable hook). Written in TypeScript, ships ESM.
 
 Published on npm as `markdansi`.
 
@@ -46,23 +46,31 @@ const { render } = await import('markdansi');
 console.log(render('# hello'));
 ```
 
-### Live streaming / in-place rendering
-For streaming output (LLM responses, logs, progress), use `createLiveRenderer` to re-render and redraw in-place. Uses terminal “synchronized output” when supported.
+### Streaming (recommended: hybrid blocks)
+If you’re streaming Markdown (LLM output), keep scrollback safe by emitting **completed fragments only**
+and writing them once (append-only; no in-place redraw).
+
+Hybrid mode streams regular lines as they complete, but buffers multi-line constructs that need context:
+- Fenced code blocks (``` / ~~~) — flushed only after the closing fence
+- Tables — flushed only after the header separator row + until the table ends
 
 ```js
-import { createLiveRenderer, render } from 'markdansi';
+import { createMarkdownStreamer, render } from 'markdansi';
 
-const live = createLiveRenderer({
-  renderFrame: (markdown) => render(markdown),
-  write: process.stdout.write.bind(process.stdout),
+const streamer = createMarkdownStreamer({
+  render: (md) => render(md, { width: process.stdout.columns ?? 80 }),
+  spacing: 'single', // collapse consecutive blank lines
 });
 
-let buffer = '';
-buffer += '# Hello\\n';
-live.render(buffer);
-buffer += '\\nMore…\\n';
-live.render(buffer);
-live.finish();
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (delta) => {
+  const chunk = streamer.push(delta);
+  if (chunk) process.stdout.write(chunk);
+});
+process.stdin.on('end', () => {
+  const tail = streamer.finish();
+  if (tail) process.stdout.write(tail);
+});
 ```
 
 ```js

package/dist/index.d.ts

@@ -1,11 +1,9 @@
-import type { LiveRenderer, LiveRendererOptions } from "./live.js";
-import { createLiveRenderer } from "./live.js";
 import { createRenderer, render as renderMarkdown } from "./render.js";
+import { createMarkdownStreamer } from "./stream.js";
 import { themes } from "./theme.js";
 import type { RenderOptions, Theme, ThemeName } from "./types.js";
-export { createLiveRenderer, createRenderer, renderMarkdown as render, themes };
+export { createMarkdownStreamer, createRenderer, renderMarkdown as render, themes, };
 export type { RenderOptions, Theme, ThemeName };
-export type { LiveRenderer, LiveRendererOptions };
 /**
  * Render Markdown to plain text (no ANSI, no hyperlinks) while preserving layout/wrapping.
  */

package/dist/index.js

@@ -1,7 +1,7 @@
-import { createLiveRenderer } from "./live.js";
 import { createRenderer, render as renderMarkdown } from "./render.js";
+import { createMarkdownStreamer } from "./stream.js";
 import { themes } from "./theme.js";
-export { createLiveRenderer, createRenderer, renderMarkdown as render, themes };
+export { createMarkdownStreamer, createRenderer, renderMarkdown as render, themes, };
 /**
  * Render Markdown to plain text (no ANSI, no hyperlinks) while preserving layout/wrapping.
  */

package/dist/stream.d.ts

@@ -0,0 +1,39 @@
+export type MarkdownStreamerSpacing = "preserve" | "single" | "tight";
+export type MarkdownStreamer = {
+    /**
+     * Push an appended Markdown delta (chunk) into the streamer.
+     * Returns ANSI text to write to the terminal (append-only).
+     */
+    push: (delta: string) => string;
+    /**
+     * Flush remaining buffered content and finish the stream.
+     * Optionally accepts one last delta.
+     */
+    finish: (finalDelta?: string) => string;
+    /**
+     * Reset internal state (buffer, fence/table detection, spacing).
+     */
+    reset: () => void;
+};
+export type MarkdownStreamerOptions = {
+    /**
+     * Function used to render a Markdown fragment (block or line) to ANSI.
+     * Must be pure (no cursor control) and must not rely on prior terminal state.
+     */
+    render: (markdown: string) => string;
+    /**
+     * Hybrid streaming: emit complete lines immediately, but buffer multi-line
+     * constructs (fenced code blocks + tables) until they are complete.
+     *
+     * This is designed for terminal scrollback safety: no in-place redraw, no cursor moves.
+     */
+    mode?: "hybrid";
+    /**
+     * Controls how blank lines are emitted.
+     * - preserve: emit blank lines exactly as received
+     * - single: collapse consecutive blank lines to a single blank line
+     * - tight: drop blank lines entirely (dense output)
+     */
+    spacing?: MarkdownStreamerSpacing;
+};
+export declare function createMarkdownStreamer(options: MarkdownStreamerOptions): MarkdownStreamer;

package/dist/stream.js

@@ -0,0 +1,193 @@
+function normalizeNewlines(input) {
+    return input.replace(/\r\n?/g, "\n");
+}
+function isFenceStart(line) {
+    const trimmed = line.trimStart();
+    const match = trimmed.match(/^(```+|~~~+)/);
+    if (!match?.[1])
+        return null;
+    const token = match[1];
+    const char = token[0] === "~" ? "~" : "`";
+    return { char, len: token.length };
+}
+function isFenceEnd(line, fence) {
+    const trimmed = line.trimStart();
+    const token = fence.char.repeat(fence.len);
+    return trimmed.startsWith(token);
+}
+function looksLikeTableHeader(line) {
+    if (!line.includes("|"))
+        return false;
+    return /[^\s|]/.test(line);
+}
+function isTableSeparator(line) {
+    // Examples:
+    // | --- | --- |
+    // |:--- | ---:|
+    // --- | ---
+    const trimmed = line.trim();
+    if (!trimmed.includes("-"))
+        return false;
+    return /^\|?(?:\s*:?-+:?\s*\|)+\s*:?-+:?\s*\|?$/.test(trimmed);
+}
+function looksLikeTableRow(line) {
+    if (!line.includes("|"))
+        return false;
+    return /[^\s|]/.test(line);
+}
+function normalizeRenderedFragment(rendered) {
+    // Markdansi intentionally prefixes some blocks (e.g. headings) with a newline when rendering
+    // whole documents. For streaming fragments, strip leading newlines to avoid double spacing.
+    const trimmedStart = rendered.replace(/^\n+/, "");
+    // For fragment streaming, normalize to a single trailing newline so spacing is controlled
+    // by the streamer (blank-line collapsing) rather than renderer block heuristics.
+    const trimmedEnd = trimmedStart.replace(/\n+$/, "");
+    return `${trimmedEnd}\n`;
+}
+export function createMarkdownStreamer(options) {
+    const render = options.render;
+    const spacing = options.spacing ?? "single";
+    let buffer = "";
+    let blankStreak = 0;
+    let started = false;
+    let heldTableHeader = null;
+    let inTable = false;
+    let tableBuffer = "";
+    let fence = null;
+    let fenceBuffer = "";
+    const emitBlankLine = () => {
+        if (!started)
+            return "";
+        if (spacing === "tight")
+            return "";
+        if (spacing === "single" && blankStreak >= 1)
+            return "";
+        blankStreak += 1;
+        return "\n";
+    };
+    const emitRendered = (markdown) => {
+        if (!markdown)
+            return "";
+        blankStreak = 0;
+        started = true;
+        return normalizeRenderedFragment(render(markdown));
+    };
+    const flushHeldHeader = () => {
+        if (!heldTableHeader)
+            return "";
+        const md = heldTableHeader;
+        heldTableHeader = null;
+        return emitRendered(md);
+    };
+    const flushTable = () => {
+        if (!inTable)
+            return "";
+        inTable = false;
+        const md = tableBuffer;
+        tableBuffer = "";
+        return emitRendered(md);
+    };
+    const flushFence = () => {
+        if (!fence)
+            return "";
+        fence = null;
+        const md = fenceBuffer;
+        fenceBuffer = "";
+        return emitRendered(md);
+    };
+    const processLine = (line) => {
+        // Fence mode: buffer everything until the closing fence.
+        if (fence) {
+            fenceBuffer += `${line}\n`;
+            if (isFenceEnd(line, fence)) {
+                return flushFence();
+            }
+            return "";
+        }
+        // Table mode: buffer table rows; flush when it ends.
+        if (inTable) {
+            if (line.trim().length === 0) {
+                return flushTable() + emitBlankLine();
+            }
+            if (!looksLikeTableRow(line)) {
+                return flushTable() + processLine(line);
+            }
+            tableBuffer += `${line}\n`;
+            return "";
+        }
+        // Blank line: flush any held header and emit spacing.
+        if (line.trim().length === 0) {
+            return flushHeldHeader() + emitBlankLine();
+        }
+        // Fence start: flush held header and enter fence mode.
+        const fenceStart = isFenceStart(line);
+        if (fenceStart) {
+            const out = flushHeldHeader();
+            fence = fenceStart;
+            fenceBuffer = `${line}\n`;
+            // Some fences are single-line in streams (rare). Handle close immediately.
+            if (isFenceEnd(line, fenceStart) &&
+                line.trimStart().match(/^(```+|~~~+)\s*$/)) {
+                return out + flushFence();
+            }
+            return out;
+        }
+        // If we held a possible table header, check if this line starts a table.
+        if (heldTableHeader) {
+            if (isTableSeparator(line) && looksLikeTableHeader(heldTableHeader)) {
+                inTable = true;
+                tableBuffer = `${heldTableHeader}\n${line}\n`;
+                heldTableHeader = null;
+                return "";
+            }
+            const out = flushHeldHeader();
+            return out + processLine(line);
+        }
+        // Potential table header: delay emission until we see the next line.
+        if (looksLikeTableHeader(line)) {
+            heldTableHeader = line;
+            return "";
+        }
+        // Normal line: render immediately.
+        return emitRendered(line);
+    };
+    const push = (delta) => {
+        if (!delta)
+            return "";
+        buffer += normalizeNewlines(delta);
+        let out = "";
+        while (true) {
+            const idx = buffer.indexOf("\n");
+            if (idx < 0)
+                break;
+            const line = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 1);
+            out += processLine(line);
+        }
+        return out;
+    };
+    const finish = (finalDelta) => {
+        let out = "";
+        if (finalDelta)
+            out += push(finalDelta);
+        if (buffer.length > 0) {
+            out += processLine(buffer);
+            buffer = "";
+        }
+        out += flushHeldHeader();
+        out += flushFence();
+        out += flushTable();
+        return out;
+    };
+    const reset = () => {
+        buffer = "";
+        blankStreak = 0;
+        started = false;
+        heldTableHeader = null;
+        inTable = false;
+        tableBuffer = "";
+        fence = null;
+        fenceBuffer = "";
+    };
+    return { push, finish, reset };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markdansi",
-	"version": "0.1.7",
+	"version": "0.2.0",
 	"description": "Tiny dependency-light markdown to ANSI converter.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -64,7 +64,7 @@
 		"micromark-util-combine-extensions": "^2.0.1",
 		"string-width": "^8.1.0",
 		"strip-ansi": "^7.1.2",
-		"supports-hyperlinks": "^4.3.0"
+		"supports-hyperlinks": "^4.4.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.10",

package/dist/live.d.ts

@@ -1,35 +0,0 @@
-export type LiveRenderer = {
-    render: (input: string) => void;
-    finish: () => void;
-};
-export type LiveRendererOptions = {
-    /**
-     * Function that converts the current full input into a rendered frame.
-     * Typically this is Markdansi's `render()` or an app-specific wrapper.
-     */
-    renderFrame: (input: string) => string;
-    /**
-     * Where to write ANSI output (usually `process.stdout.write.bind(process.stdout)`).
-     */
-    write: (chunk: string) => void;
-    /**
-     * Enable terminal "synchronized output" framing (DEC private mode 2026).
-     * Most terminals ignore this sequence if unsupported.
-     */
-    synchronizedOutput?: boolean;
-    /**
-     * Hide cursor during live updates.
-     */
-    hideCursor?: boolean;
-    /**
-     * Terminal width in columns used for row accounting.
-     * If omitted, defaults to 80.
-     */
-    width?: number;
-};
-/**
- * Create a live renderer that repeatedly re-renders the entire buffer and redraws in-place.
- *
- * This is intentionally "terminal plumbing" and renderer-agnostic: you inject `renderFrame()`.
- */
-export declare function createLiveRenderer(options: LiveRendererOptions): LiveRenderer;

package/dist/live.js

@@ -1,75 +0,0 @@
-import stringWidth from "string-width";
-import stripAnsi from "strip-ansi";
-const BSU = "\u001b[?2026h";
-const ESU = "\u001b[?2026l";
-const HIDE_CURSOR = "\u001b[?25l";
-const SHOW_CURSOR = "\u001b[?25h";
-const CLEAR_TO_END = "\u001b[0J";
-function cursorUp(lines) {
-    if (lines <= 0)
-        return "";
-    return `\u001b[${lines}A`;
-}
-/**
- * Create a live renderer that repeatedly re-renders the entire buffer and redraws in-place.
- *
- * This is intentionally "terminal plumbing" and renderer-agnostic: you inject `renderFrame()`.
- */
-export function createLiveRenderer(options) {
-    let previousRows = 0;
-    let cursorHidden = false;
-    const synchronizedOutput = options.synchronizedOutput !== false;
-    const hideCursor = options.hideCursor !== false;
-    const width = typeof options.width === "number" &&
-        Number.isFinite(options.width) &&
-        options.width > 0
-        ? Math.floor(options.width)
-        : 80;
-    const countRows = (text) => {
-        const lines = text.split("\n");
-        if (lines.length > 0 && lines.at(-1) === "")
-            lines.pop();
-        let rows = 0;
-        for (const line of lines) {
-            const visible = stripAnsi(line);
-            const w = stringWidth(visible);
-            rows += Math.max(1, Math.ceil(Math.max(0, w) / width));
-        }
-        return rows;
-    };
-    const render = (input) => {
-        const renderedRaw = options.renderFrame(input);
-        const rendered = renderedRaw.endsWith("\n")
-            ? renderedRaw
-            : `${renderedRaw}\n`;
-        const lines = rendered.split("\n");
-        if (lines.length > 0 && lines.at(-1) === "")
-            lines.pop();
-        const newRows = countRows(rendered);
-        let frame = "";
-        if (hideCursor && !cursorHidden) {
-            frame += HIDE_CURSOR;
-            cursorHidden = true;
-        }
-        if (synchronizedOutput)
-            frame += BSU;
-        frame += previousRows > 0 ? `${cursorUp(previousRows)}\r` : "\r";
-        frame += CLEAR_TO_END;
-        for (const line of lines) {
-            frame += "\r";
-            frame += line;
-            frame += "\r\n";
-        }
-        if (synchronizedOutput)
-            frame += ESU;
-        options.write(frame);
-        previousRows = newRows;
-    };
-    const finish = () => {
-        if (hideCursor && cursorHidden) {
-            options.write(SHOW_CURSOR);
-            cursorHidden = false;
-        }
-    };
-    return { render, finish };
-}