termrender 0.5.0__tar.gz → 0.6.1__tar.gz

{termrender-0.5.0 → termrender-0.6.1}/CHANGELOG.md

@@ -1,6 +1,78 @@
 # CHANGELOG
 
 
+## v0.6.1 (2026-04-08)
+
+### Bug Fixes
+
+- **borders**: Grow render_box to fit overflowing content and titles
+  ([`dc108c8`](https://github.com/CaptainCrouton89/termrender/commit/dc108c8242763828245569f719abce64b26ddf5b))
+
+mermaid-ascii's --maxWidth is non-strict, so a child mermaid block can return lines wider than the
+  panel's allocated content area. Previously the side walls floated outward to accommodate the
+  content while the top/bottom borders stayed at the requested width, leaving corner glyphs one
+  column inside the side walls and producing a visibly jagged box.
+
+render_box now measures the widest content line (and the title) and grows its effective width up
+  front so all four borders land at the same column. Trade-off: the box may overflow its parent
+  allocation, but the box itself is internally consistent.
+
+
+## v0.6.0 (2026-04-07)
+
+### Features
+
+- Add diff, charts, stat, timeline, tasklist, and inline badges
+  ([`e14f615`](https://github.com/CaptainCrouton89/termrender/commit/e14f615ae8d0723405db61c79b0f858d7bf0f863))
+
+New block-level directives: - :::diff — colored unified diff with +/- gutters - :::bar — multi-bar
+  chart with sub-cell precision via eighth blocks - :::progress — single-line progress bar (auto
+  color by ratio) - :::gauge — three-line meter (auto color by load threshold) - :::stat — KPI tile
+  with label, value, trend arrow + delta, caption - :::timeline — vertical event list with bullet
+  markers and connectors - :::tasklist — checkbox list (also auto-detected from any markdown list
+  with [x]/[ ]/[!] markers)
+
+New inline role: - :badge[text]{color=green} — colored pill, reuses new InlineSpan fg/bg fields so
+  future inline roles drop in trivially.
+
+Cross-cutting changes: - InlineSpan gained fg/bg fields; render_spans and span-slicers in text.py
+  and table.py honor them. - _merge_plain_spans coalesces mistune's text fragments before role
+  expansion (mistune splits on `[`, which would otherwise break :badge[...]). - _render_list_item
+  now uses visual_len(prefix) so styled checkbox prefixes don't break indent math. - STAT joins
+  PANEL/CALLOUT/CODE in the border-aware width path. - progress and gauge added to
+  _SELF_CLOSING_DIRECTIVES (atomic, no body); stat requires an explicit closer so it can hold a
+  caption.
+
+63 new tests across six test files. All 94 tests pass.
+
+- **cli**: Add --watch mode for live re-rendering
+  ([`4223ad8`](https://github.com/CaptainCrouton89/termrender/commit/4223ad86805b0b3ad45450bd7ca4441a668f0e23))
+
+Re-renders the file whenever its mtime changes, with terminal-resize detection and inline error
+  display so the watcher survives malformed input. Uses the alternate screen buffer so Ctrl+C
+  cleanly restores the prior terminal state.
+
+Composes with --tmux: --tmux --watch points the spawned pane at the real file path (skipping the
+  tempfile path) so the live loop runs inside the side pane.
+
+### Refactoring
+
+- **parser**: Require strictly more colons on outer fences
+  ([`4a501d9`](https://github.com/CaptainCrouton89/termrender/commit/4a501d917db191f758874bb6c3d922c879a763be))
+
+Drops the depth-counter that allowed `:::outer ... :::inner ... ::: ... :::` nesting with same colon
+  counts. Termrender now matches the standard followed by MyST, Pandoc fenced divs,
+  markdown-it-container, and CommonMark fenced code blocks: an opener can only nest inside another
+  directive if its colon count is strictly less than the outer's.
+
+A closer with a non-matching colon count is treated as body content and falls through to the
+  recursive parse(), which is what makes nested directives work in the first place.
+
+Fixtures in test_column_alignment.py rewritten to ascending colon counts (7/6/5/4/3 for the
+  showpiece, 5/4/3 for columns_tree, 4/3 for panel_tree). test_same_colon_nesting_backward_compat
+  deleted — its behavior is no longer supported.
+
+
 ## v0.5.0 (2026-04-06)
 
 ### Features

{termrender-0.5.0 → termrender-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 0.5.0
+Version: 0.6.1
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender

{termrender-0.5.0 → termrender-0.6.1}/src/termrender/CLAUDE.md

@@ -10,11 +10,11 @@
 
 `layout.py` imports `fix_mermaid_encoding` from `renderers/mermaid.py` — the only reverse dependency from layout into renderers. Reorganizing `renderers/` must account for this import. The two subprocess call sites differ: layout uses `check=True` (non-zero exit raises `CalledProcessError` → caught → raw source fallback); the renderer omits `check` (non-zero exit silently reads `stdout`, which may be empty or partial). See `renderers/CLAUDE.md` for encoding-fix details.
 
-## Directive nesting: depth counter, not stack entries
+## Directive nesting: outer must have more colons than inner
 
 The parser handles two directive syntaxes through different passes: colon directives (`:::name`) are extracted in pass 1 via regex in `_split_directives`, while backtick fence directives (`` ```{name} ``) are resolved in pass 2 via mistune's AST walk in `_convert_ast`. Both paths funnel through `_directive_to_block` for block construction.
 
-For colon directives, the parser tracks nesting with a `depth` integer inside the top stack entry, not separate stack entries (parser.py:241–306). A closer `:::` only pops the stack when `depth == 1`; otherwise it decrements depth and treats the closer as body content. Consequence: innermost closers appear verbatim in the body of the parent and are re-parsed on the recursive `parse()` call at line 351.
+For colon directives, closers are paired strictly by colon count. A closer whose colon count differs from the open directive's colon count is treated as body content; the recursive `parse()` call inside `_directive_to_block` re-parses it as an inner directive. This matches the standard rule used by MyST, Pandoc fenced divs, markdown-it-container, and CommonMark fenced code blocks: outer fences must use strictly more colons than the inner fences they wrap, making opener/closer pairing unambiguous.
 
 Max recursion depth is 50; exceeding it raises `ValueError`, not `DirectiveError`. Both the render path and `--check` path in `__main__.py` catch `ValueError` and map it to exit code 2 (`EXIT_SYNTAX`).
 
@@ -50,9 +50,23 @@ Max recursion depth is 50; exceeding it raises `ValueError`, not `DirectiveError
 
 ## `--tmux`: exit code reflects pane creation, auto-sizing runs a full render, tempfiles leak
 
-`__main__.py:229`: after `tmux split-window` succeeds the parent exits `EXIT_OK` immediately — the pane renders asynchronously. Render errors surface only inside the pane. `--check` is silently dropped with `--tmux` (exit at line 229 precedes the `--check` branch at line 231). Tempfile cleanup is embedded as `... | less -R; rm -f <tmpfile>` (line 214); `less` killed abnormally (SIGKILL, closed session) leaks `/tmp/termrender-*.md`.
+`__main__.py:357`: after `tmux split-window` succeeds the parent exits `EXIT_OK` immediately — the pane renders asynchronously. Render errors surface only inside the pane. `--check` is silently dropped with `--tmux` (exit at line 357 precedes the `--check` branch at line 368), even though `--tmux` now runs its own `parse()` call (lines 253–266) for fail-fast syntax validation before spawning the pane. The `--check` "ok" message and exit-code contract are not honoured.
 
-When `--width` is omitted, `--tmux` calls `render(source, width=80, color=False)` (lines 177–185) to measure content width — mermaid subprocesses fire and `TERMRENDER_CJK` mutations apply here. Any exception silently falls back to `pane_width=80`. The pane is capped to `tmux #{pane_width} - 10`; if the tmux query fails, no cap is applied. Minimum enforced pane width is 20.
+Tempfile cleanup is embedded as `... | less -R; rm -f <tmpfile>` (line 339); `less` killed abnormally (SIGKILL, closed session) leaks `/tmp/termrender-*.md`. `--tmux --watch` skips tempfile creation entirely — the pane is pointed at the real file path, so no leak.
+
+When `--width` is omitted, `--tmux` calls `render(source, width=80, color=False)` (lines 283–290) to measure content width — mermaid subprocesses fire and `TERMRENDER_CJK` mutations apply here. Any exception silently falls back to `pane_width=80`. The pane is capped to `tmux #{pane_width} - 10`; if the tmux query fails, no cap is applied. Minimum enforced pane width is 20.
+
+## `--watch`: re-renders on resize as well as file change; errors are inline, not fatal
+
+`_watch_loop` (lines 99–169) polls `os.path.getmtime` every 0.2 s and also re-renders when `shutil.get_terminal_size()` changes — so a terminal resize triggers a re-render even with no file edit. `width=None` is passed to `render()` each cycle, so auto-detection always uses current pane width.
+
+The loop catches bare `Exception` (line 142) to keep the watcher alive across render errors; errors appear as a one-line message in the pane, not as an exit. `DirectiveError`, `TerminalError`, and `ValueError` (nesting depth) are each caught separately with distinct prefixes for that same reason — the watcher never exits on render failure, only on `KeyboardInterrupt`.
+
+The alternate screen buffer (`\033[?1049h` / `\033[?1049l`) is entered on start and restored in a `finally` block, so Ctrl+C cleanly returns to the prior terminal state. `--watch` requires a FILE argument; stdin cannot be watched (polled by path, not fd).
+
+## `TERMRENDER_COLOR=1` forces color when stdout is not a tty
+
+`use_color` (lines 361–363 and 388–390) is `True` when stdout is a tty OR `TERMRENDER_COLOR == "1"`. The tmux pane command is prefixed with `TERMRENDER_COLOR=1` (lines 334, 337) so color survives the `| less -R` pipe. Setting this env var in scripts achieves the same effect — it overrides the tty check entirely.
 
 ## `_EMOJI_WIDE_RANGES` must stay sorted by codepoint
 

{termrender-0.5.0 → termrender-0.6.1}/src/termrender/__main__.py

@@ -74,6 +74,8 @@ examples:
   echo '# Hello' | termrender     Quick inline render
 
   termrender --tmux doc.md            Render in a new tmux side pane
+  termrender --watch doc.md           Live-render in current terminal
+  termrender --tmux --watch doc.md    Live-render in a new tmux side pane
   termrender <<'EOF'
   :::panel{title="Status" color="green"}
   - All systems operational
@@ -94,6 +96,79 @@ def _error(msg: str, *, fix: str | None = None, hint: str | None = None,
     sys.exit(code)
 
 
+def _watch_loop(file_path: str, *, color: bool, poll_interval: float = 0.2) -> None:
+    """Re-render `file_path` whenever its mtime changes.
+
+    Uses the alternate screen buffer so the prior terminal state is restored
+    on exit. Width is re-detected from the current terminal each render so
+    pane/window resizes are picked up automatically. Render errors are shown
+    inline rather than crashing the watcher — fix the file and save again.
+    """
+    import time
+
+    last_mtime: float | None = None
+    last_size: tuple[int, int] = (0, 0)
+
+    def _draw(body: str, status: str) -> None:
+        # \033[?25l hide cursor, \033[2J clear, \033[H home
+        sys.stdout.write("\033[?25l\033[2J\033[H")
+        sys.stdout.write(body)
+        if not body.endswith("\n"):
+            sys.stdout.write("\n")
+        # Status line at the bottom — dim if color is enabled
+        if color:
+            sys.stdout.write(f"\033[2m{status}\033[0m\n")
+        else:
+            sys.stdout.write(f"{status}\n")
+        sys.stdout.flush()
+
+    def _render_now() -> None:
+        try:
+            with open(file_path, "r") as f:
+                source = f.read()
+        except FileNotFoundError:
+            body = f"termrender: file not found: {file_path}\n"
+        except OSError as e:
+            body = f"termrender: cannot read {file_path}: {e}\n"
+        else:
+            try:
+                body = render(source, width=None, color=color)
+            except DirectiveError as e:
+                body = f"termrender: syntax error: {e}\n"
+            except TerminalError as e:
+                body = f"termrender: terminal error: {e}\n"
+            except ValueError as e:
+                body = f"termrender: nesting error: {e}\n"
+            except Exception as e:  # noqa: BLE001 — keep watcher alive
+                body = f"termrender: render error: {e}\n"
+        _draw(body, f"watching {file_path} — Ctrl+C to exit")
+
+    # Enter alternate screen buffer
+    sys.stdout.write("\033[?1049h")
+    sys.stdout.flush()
+    try:
+        while True:
+            try:
+                mtime = os.path.getmtime(file_path)
+            except FileNotFoundError:
+                mtime = None
+            # Re-render on file change OR terminal resize
+            import shutil as _shutil
+            size = _shutil.get_terminal_size()
+            size_tuple = (size.columns, size.lines)
+            if mtime != last_mtime or size_tuple != last_size:
+                last_mtime = mtime
+                last_size = size_tuple
+                _render_now()
+            time.sleep(poll_interval)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # Show cursor, leave alternate screen buffer
+        sys.stdout.write("\033[?25h\033[?1049l")
+        sys.stdout.flush()
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(
         prog="termrender",
@@ -136,6 +211,11 @@ def main() -> None:
         action="store_true",
         help="open rendered output in a new tmux side pane (requires tmux)",
     )
+    parser.add_argument(
+        "--watch",
+        action="store_true",
+        help="re-render whenever FILE changes on disk (requires a file argument)",
+    )
     parser.add_argument(
         "-V", "--version",
         action="version",
@@ -143,6 +223,14 @@ def main() -> None:
     )
     args = parser.parse_args()
 
+    # --watch needs a real file path to poll; stdin can't be watched.
+    if args.watch and args.file is None:
+        _error(
+            "--watch requires a FILE argument",
+            fix="pass a markdown file path; stdin cannot be watched",
+            hint="termrender --watch doc.md",
+        )
+
     # Determine input source
     infile = args.file if args.file is not None else sys.stdin
     if infile is sys.stdin and sys.stdin.isatty():
@@ -213,23 +301,43 @@ def main() -> None:
             pass
         pane_width = max(pane_width, 20)  # absolute minimum
 
-        # Save source so the new pane can render it
-        with tempfile.NamedTemporaryFile(
-            mode="w", suffix=".md", prefix="termrender-", delete=False,
-        ) as f:
-            f.write(source)
-            tmpfile = f.name
+        # Watch mode points the new pane at the user's real file so edits
+        # propagate; non-watch mode snapshots source into a tempfile.
+        tmpfile: str | None = None
+        if args.watch:
+            # args.file is guaranteed non-None by the earlier --watch check.
+            source_path = args.file.name
+        else:
+            with tempfile.NamedTemporaryFile(
+                mode="w", suffix=".md", prefix="termrender-", delete=False,
+            ) as f:
+                f.write(source)
+                tmpfile = f.name
+            source_path = tmpfile
 
         # Rebuild command without --tmux to avoid recursion
-        cmd_parts = ["termrender", shlex.quote(tmpfile)]
+        cmd_parts = ["termrender", shlex.quote(source_path)]
         if args.no_color:
             cmd_parts.append("--no-color")
         if args.cjk:
             cmd_parts.append("--cjk")
-        cmd_parts.extend(["-w", str(pane_width)])
+        if args.watch:
+            # No -w: watcher re-detects pane width per render so resizes
+            # pick up automatically.
+            cmd_parts.append("--watch")
+        else:
+            cmd_parts.extend(["-w", str(pane_width)])
 
-        # TERMRENDER_COLOR=1 forces color on despite stdout piping to less
-        pane_cmd = "TERMRENDER_COLOR=1 " + " ".join(cmd_parts) + " | less -R; rm -f " + shlex.quote(tmpfile)
+        if args.watch:
+            # Watch mode owns the pane (alternate screen buffer); no less,
+            # no tempfile cleanup needed.
+            pane_cmd = "TERMRENDER_COLOR=1 " + " ".join(cmd_parts)
+        else:
+            # TERMRENDER_COLOR=1 forces color on despite stdout piping to less
+            pane_cmd = (
+                "TERMRENDER_COLOR=1 " + " ".join(cmd_parts)
+                + " | less -R; rm -f " + shlex.quote(source_path)
+            )
 
         try:
             subprocess.run(
@@ -237,15 +345,25 @@ def main() -> None:
                 check=True,
             )
         except FileNotFoundError:
-            os.unlink(tmpfile)
+            if tmpfile:
+                os.unlink(tmpfile)
             _error("tmux not found", fix="install tmux or omit --tmux")
         except subprocess.CalledProcessError:
-            os.unlink(tmpfile)
+            if tmpfile:
+                os.unlink(tmpfile)
             _error("failed to create tmux pane",
                    hint="check that tmux is running and has space for a new pane")
 
         sys.exit(EXIT_OK)
 
+    # --watch: live-render in the current terminal
+    if args.watch:
+        use_color = not args.no_color and (
+            sys.stdout.isatty() or os.environ.get("TERMRENDER_COLOR") == "1"
+        )
+        _watch_loop(args.file.name, color=use_color)
+        sys.exit(EXIT_OK)
+
     # --check: validate only, no rendering
     if args.check:
         try:

{termrender-0.5.0 → termrender-0.6.1}/src/termrender/blocks.py

@@ -25,6 +25,12 @@ class BlockType(Enum):
     TABLE = "table"
     LIST = "list"
     LIST_ITEM = "list_item"
+    DIFF = "diff"
+    BAR = "bar"
+    PROGRESS = "progress"
+    GAUGE = "gauge"
+    STAT = "stat"
+    TIMELINE = "timeline"
 
 
 @dataclass
@@ -35,6 +41,8 @@ class InlineSpan:
     bold: bool = False
     italic: bool = False
     code: bool = False
+    fg: str | None = None
+    bg: str | None = None
 
 
 @dataclass

{termrender-0.5.0 → termrender-0.6.1}/src/termrender/emit.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 from termrender.blocks import Block, BlockType
-from termrender.renderers import panel, columns, tree, code, text, divider, quote, mermaid, table
+from termrender.renderers import (
+    panel, columns, tree, code, text, divider, quote, mermaid, table,
+    diff, charts, stat, timeline,
+)
 
 
 def emit_block(block: Block, color: bool) -> list[str]:
@@ -45,6 +48,24 @@ def emit_block(block: Block, color: bool) -> list[str]:
         case BlockType.DIVIDER:
             return divider.render(block, color)
 
+        case BlockType.DIFF:
+            return diff.render(block, color)
+
+        case BlockType.BAR:
+            return charts.render_bar(block, color)
+
+        case BlockType.PROGRESS:
+            return charts.render_progress(block, color)
+
+        case BlockType.GAUGE:
+            return charts.render_gauge(block, color)
+
+        case BlockType.STAT:
+            return stat.render(block, color, render_child=emit_block)
+
+        case BlockType.TIMELINE:
+            return timeline.render(block, color)
+
         case _:
             return []
 

{termrender-0.5.0 → termrender-0.6.1}/src/termrender/layout.py

@@ -17,7 +17,7 @@ def resolve_width(block: Block, available: int) -> None:
     block.width = available
 
     bt = block.type
-    if bt in (BlockType.PANEL, BlockType.CALLOUT, BlockType.CODE):
+    if bt in (BlockType.PANEL, BlockType.CALLOUT, BlockType.CODE, BlockType.STAT):
         border_overhead = visual_len("│") * 2 + 2  # left border + left pad + right pad + right border
         inner = max(available - border_overhead, 1)
         for child in block.children:
@@ -160,6 +160,41 @@ def resolve_height(block: Block) -> None:
     elif bt == BlockType.QUOTE:
         block.height = sum(c.height or 0 for c in block.children) + (1 if block.attrs.get("author") or block.attrs.get("by") else 0)
 
+    elif bt == BlockType.DIFF:
+        source = block.attrs.get("source", "")
+        lines = source.split("\n") if source else [""]
+        # Drop pure-blank trailing line that comes from terminating newline
+        if lines and lines[-1] == "":
+            lines = lines[:-1]
+        block.height = max(len(lines), 1) + 2  # top/bottom border
+
+    elif bt == BlockType.BAR:
+        items = block.attrs.get("items", [])
+        title_h = 1 if block.attrs.get("title") else 0
+        block.height = max(len(items), 1) + title_h
+
+    elif bt == BlockType.PROGRESS:
+        block.height = 1
+
+    elif bt == BlockType.GAUGE:
+        # label line + bar line + value line
+        block.height = 3
+
+    elif bt == BlockType.STAT:
+        # top border + label + value + delta + caption lines + bottom border
+        caption_h = sum(c.height or 0 for c in block.children)
+        delta_h = 1 if block.attrs.get("delta") else 0
+        block.height = 2 + 1 + 1 + delta_h + caption_h  # borders + label + value + delta + caption
+
+    elif bt == BlockType.TIMELINE:
+        entries = block.attrs.get("entries", [])
+        title_h = 1 if block.attrs.get("title") else 0
+        # Each entry takes 1 line + 1 connector line between entries (none after last)
+        if entries:
+            block.height = title_h + len(entries) * 2 - 1
+        else:
+            block.height = max(title_h, 1)
+
     else:
         block.height = sum(c.height or 0 for c in block.children)