markdansi 0.1.7 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Peter Steinberger
+\g<1>2026 Peter Steinberger
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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/cli.d.ts

@@ -13,4 +13,5 @@ export declare function handleStdoutEpipe(): void;
  * Parse CLI arguments into RenderOptions-ish object (plus in/out paths).
  */
 export declare function parseArgs(argv: string[]): CliArgs;
+export declare function isDirectCliInvocation(metaUrl: string, argv1?: string): boolean;
 export {};

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { render } from "./index.js";
 /**
  * Ignore EPIPE when downstream (e.g., `head`) closes early.
@@ -157,10 +157,19 @@ function main() {
         process.stdout.write(output);
     }
 }
+export function isDirectCliInvocation(metaUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        const entry = fs.realpathSync(argv1);
+        const self = fs.realpathSync(fileURLToPath(metaUrl));
+        return entry === self;
+    }
+    catch {
+        return false;
+    }
+}
 // Only run the CLI when executed directly, not when imported for tests.
-const entryHref = process.argv[1]
-    ? pathToFileURL(process.argv[1]).href
-    : undefined;
-if (import.meta.url === entryHref) {
+if (isDirectCliInvocation(import.meta.url, process.argv[1])) {
     main();
 }

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/render.js

@@ -565,13 +565,15 @@ function renderTable(node, ctx) {
     const widths = new Array(colCount).fill(1);
     const aligns = node.align || [];
     const pad = ctx.options.tablePadding;
+    const padStr = " ".repeat(Math.max(0, pad));
     const minContent = Math.max(1, ctx.options.tableEllipsis.length + 1);
     // ensure we always have room for at least one visible char + ellipsis + padding
     const minColWidth = Math.max(1, pad * 2 + minContent);
     cells.forEach((row) => {
         row.forEach((cell, idx) => {
+            const padded = `${padStr}${cell}${padStr}`;
             // Cap each column to MAX_COL but keep at least 1
-            widths[idx] = Math.max(widths[idx], Math.min(MAX_COL, visibleWidth(cell)));
+            widths[idx] = Math.max(widths[idx], Math.min(MAX_COL, visibleWidth(padded)));
         });
     });
     const totalWidth = widths.reduce((a, b) => a + b, 0) + 3 * colCount + 1;
@@ -592,13 +594,16 @@ function renderTable(node, ctx) {
     }
     const renderRow = (row, isHeader = false) => {
         const linesPerCol = row.map((cell, idx) => {
-            const padded = ` ${cell} `;
             const target = Math.max(minContent, widths[idx] - pad * 2);
-            const cellText = ctx.options.tableTruncate
+            const content = ctx.options.tableTruncate
                 ? truncateCell(cell, target, ctx.options.tableEllipsis)
-                : padded;
-            const wrapped = wrapText(cellText, ctx.options.wrap ? target : Number.MAX_SAFE_INTEGER, ctx.options.wrap);
-            return wrapped.map((l) => padCell(` ${l} `, widths[idx], aligns[idx] ?? "left", ctx.options.tablePadding));
+                : cell;
+            const wrapped = wrapText(content, ctx.options.wrap ? target : Number.MAX_SAFE_INTEGER, ctx.options.wrap);
+            return wrapped.map((l) => {
+                const aligned = padCell(l, target, aligns[idx] ?? "left");
+                const padded = `${padStr}${aligned}${padStr}`;
+                return padCell(padded, widths[idx], "left");
+            });
         });
         // Row height = max wrapped lines in any column; pad shorter ones
         const height = Math.max(...linesPerCol.map((c) => c.length));

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.1",
 	"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 };
-}