@vincemakes/kiso-tui-cells 0.9.0 → 0.11.0

package/dist/md.d.ts

@@ -0,0 +1,137 @@
+/**
+ * TUI2-MD — the markdown renderer. Hand-rolled, zero dependencies, and
+ * deliberately a SUBSET: the constructs assistant prose actually uses,
+ * rendered under the mono discipline (attributes over colours, zero
+ * syntax highlighting).
+ *
+ * THE BLOCK-FREEZE DISCIPLINE. kiso's committed bytes are never
+ * re-emitted (ADR-0046) — the terminal's own scrollback is the
+ * transcript. A renderer that re-lexes the whole message per delta (the
+ * shape a whole-text parser forces on you) can therefore not be used
+ * here at all: it would need to repaint lines that have already left
+ * the live region. So the scanner below IS the streaming state machine.
+ * It consumes appended text and yields two things:
+ *
+ *   - CLOSED blocks: their source is final, so their render is final;
+ *     the compositor commits them through the path it already had.
+ *   - the OPEN TAIL block: the live region's occupant, re-rendered in
+ *     place per delta, bounded by construction (one block).
+ *
+ * The freeze property — a closed block's rendered lines never change as
+ * more text arrives — is earned by ONE rule: block boundaries are
+ * decided only on COMPLETE lines. A trailing partial line renders
+ * eagerly but can never close anything, because a decision taken on an
+ * incomplete line can be wrong ("#" is a heading until it becomes
+ * "#hashtag") and a wrong decision here is a wrong commit.
+ *
+ * Everything else follows: an unclosed `**` renders literal and flips
+ * when it closes, but only ever inside the open block; a fence body
+ * line is line-local (no highlighting means no cross-line lexer state),
+ * so it closes the instant its newline arrives and long code blocks
+ * never bloat the live region; a table re-layouts as rows stream, and
+ * only inside the tail.
+ *
+ * The style table is the round's normative one (the owner's circled
+ * group D): the BLOCK half is `blockBody` below, the INLINE half is
+ * `inlineSpans`, and every entry is pinned by a fixture rather than
+ * described twice.
+ */
+/** The block kinds. `fence-open`/`fence-line` are separate kinds on
+ *  purpose: a fence's rows must be able to freeze ONE AT A TIME. */
+export type MdKind = "para" | "heading" | "list" | "table" | "quote" | "rule" | "fence-open" | "fence-line";
+/** One block: its SOURCE lines, never a rendered form. The render is a
+ *  pure function of (block, width), which is what makes the freeze
+ *  property a property of the scanner alone. */
+export interface MdBlock {
+    readonly kind: MdKind;
+    readonly lines: readonly string[];
+    /** a blank row precedes this block — the markdown rhythm, owned here
+     *  rather than by the compositor's W11 join formula (which reads row
+     *  COUNTS and so cannot express "no blank between two rows of one
+     *  fence"). */
+    readonly gap: boolean;
+    /** the fence's language tag; "" everywhere else. */
+    readonly lang: string;
+}
+export declare class MdStream {
+    #private;
+    /** Append streamed text. Only COMPLETE lines reach the state machine. */
+    push(text: string): void;
+    /** The message ended: the trailing partial line is a complete line
+     *  after all, and the open block closes. */
+    end(): void;
+    /** Every block so far: `closed()` of them are FINAL, and at most one
+     *  open tail follows. Fresh objects — a closed block's source can
+     *  never be reached through this. */
+    blocks(): readonly MdBlock[];
+    /** How many leading blocks are CLOSED — the commit-eligible count. */
+    closed(): number;
+}
+/** The whole message at once — the freeze property's oracle, and the
+ *  path a non-streaming caller takes. */
+export declare function renderMarkdown(text: string, W: number): string[];
+/** One block's screen rows. Pure in (block, W) — this is the whole
+ *  freeze guarantee: same source, same width, same bytes, forever. */
+export declare function renderBlock(b: MdBlock, W: number): string[];
+/**
+ * The inline pass — the mono style table applied to one block's text.
+ *
+ * Scoped to `**bold**`, `*italic*`, `` `code` ``, `[text](url)` and the
+ * backslash escape, with two rules that matter more than coverage:
+ *
+ *   RAW UNTIL CLOSED — an opener with no closer in this text stays
+ *   literal. That is what lets a half-streamed `**` show its asterisks
+ *   and flip the instant the closer lands, inside the live block and
+ *   nowhere else.
+ *
+ *   CLOSE BACK TO `base` — the block's own style (a heading's bold, a
+ *   quote's dim) is passed in, and every span reopens it on the way
+ *   out, so a nested span can never strand it. Italic is the one span
+ *   that closes surgically (SGR 23), because it can.
+ *
+ * Documented deviations from CommonMark: `_` never emphasizes (it is a
+ * character in identifiers far more often than a marker in prose);
+ * emphasis does not nest across a code span; `~~` is not a construct at
+ * all — the markers are content (the strict tokenizer both reference
+ * implementations converged on, taken to its honest conclusion, since
+ * SGR 9's terminal support is too fragmented to promise).
+ */
+export declare function inlineSpans(text: string, base: string): string;
+/** Split a table line into cells. The `|` walls are found on the RAW
+ *  line, but a pipe INSIDE a code span is content — two independent
+ *  reference implementations both patched exactly this, because a
+ *  command in a cell (`grep a | wc`) is common and splitting it puts
+ *  the human's own text in the wrong column. A backslash-escaped pipe
+ *  is content too. */
+export declare function splitCells(line: string): string[];
+export type MdAlign = "left" | "center" | "right";
+export interface MdTable {
+    readonly header: readonly string[];
+    readonly align: readonly MdAlign[];
+    readonly rows: readonly (readonly string[])[];
+}
+/** The table shape, or null when these lines are NOT a table.
+ *
+ *  Two rejections, both borrowed: a second line that is not a delimiter
+ *  row means this is prose that contains pipes; and a body row carrying
+ *  MORE columns than the header is malformed — rendering it would have
+ *  to guess where the extra content belongs, and a guess printed into
+ *  scrollback is indistinguishable from a fact. Rejected tables fall
+ *  back to their own source bytes, which are still valid markdown. */
+export declare function tableShape(lines: readonly string[]): MdTable | null;
+/**
+ * Wrap styled text into rows of at most W columns, with a HANGING
+ * INDENT: `first` prefixes the first row, `hang` every later one, and
+ * the text column is what continuations align to.
+ *
+ * The SGR spans open at a break are closed at the row's end and
+ * reopened at the next row's start, so no style leaks into the padding
+ * and none is lost across the break. Italic's own close (23) is
+ * understood, so `\x1b[3m…\x1b[23m` inside a bold heading tracks
+ * correctly.
+ *
+ * Every emitted row measures ≤ W through the SAME width authority the
+ * compositor's invariant ① measures with — which is the only way the
+ * two can agree.
+ */
+export declare function mdWrap(text: string, W: number, first: string, hang: string): string[];