termrender 0.2.1__tar.gz → 0.4.0__tar.gz

{termrender-0.2.1 → termrender-0.4.0}/.gitignore

@@ -7,3 +7,6 @@ build/
 .eggs/
 *.egg
 .sisyphus/
+
+# Sisyphus
+.sisyphus

{termrender-0.2.1 → termrender-0.4.0}/CHANGELOG.md

@@ -1,6 +1,50 @@
 # CHANGELOG
 
 
+## v0.4.0 (2026-04-05)
+
+### Features
+
+- **parser**: Variable colon counts, backtick fence directives, and gloam-inspired theming
+  ([`47fac7f`](https://github.com/CaptainCrouton89/termrender/commit/47fac7fcf13d33e5d9986d3f9ca42ddaf5e7207d))
+
+Parser changes: - Support 3+ colon openers/closers with stack-based matching - Backtick fence
+  directive syntax (```{name}) via mistune AST interception - Option line stripping (:key: value)
+  into directive attrs
+
+CLI changes: - Syntax validation before tmux pane creation (no orphan panes on bad input) - TTY
+  auto-detect for color (disabled when piping, forced in tmux subprocess)
+
+Theming (gloam-inspired defaults): - Headings: depth-based colored fg + dim tinted bg
+  (yellow→green→cyan→blue→magenta) - Inline code: cyan (aqua) - Panel borders: dim gray with yellow
+  bold titles - Table borders: blue dim, headers: yellow bold on dim-blue bg - Background color
+  support added to style()
+
+24 new tests across two test files.
+
+
+## v0.3.0 (2026-04-05)
+
+### Documentation
+
+- Update CLAUDE.md notes for mermaid, tmux, and layout
+  ([`9e104d5`](https://github.com/CaptainCrouton89/termrender/commit/9e104d5ee7bad9a57902e79586c02b0e8d80c589))
+
+### Features
+
+- **cli**: Auto-size tmux pane to fit rendered content
+  ([`91f0414`](https://github.com/CaptainCrouton89/termrender/commit/91f0414d0bf8bfbe4d7167159b928ed9c736db74))
+
+- **mermaid**: Pass width and vertical padding to mermaid-ascii
+  ([`96145c2`](https://github.com/CaptainCrouton89/termrender/commit/96145c2789a52a4d94e9bc5f4adf7f3a88d8501f))
+
+- **table**: Auto-wrap cell content when columns overflow
+  ([`0fae56f`](https://github.com/CaptainCrouton89/termrender/commit/0fae56f8f00260c3263671df9a63a5bea17820bb))
+
+When a table exceeds available width, cells now wrap text within their proportionally-shrunk column
+  widths instead of overflowing. Layout height calculation updated to account for multi-line cells.
+
+
 ## v0.2.1 (2026-04-05)
 
 ### Bug Fixes

termrender-0.4.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+termrender renders directive-flavored markdown to ANSI terminal output. LLM agents describe layout with `:::directives` (panels, columns, trees, callouts, etc.) and termrender produces styled terminal output. Public API: `from termrender import render`.
+
+## Commands
+
+```bash
+# Install in dev mode
+pip install -e .
+
+# Run tests
+pytest tests/
+pytest tests/test_column_alignment.py::TestColumnAlignment::test_showpiece_renders_without_error
+
+# Run the CLI
+python -m termrender <file.md>
+echo ':::panel{title="Hi"}\nHello\n:::' | python -m termrender
+
+# Build
+python -m build
+```
+
+No linter or formatter is configured.
+
+## Architecture
+
+Three-stage pipeline: **parse → layout → emit**.
+
+1. **Parse** (`parser.py`) — Two-pass: regex extracts `:::directives` first, then mistune v3 processes markdown segments. Produces a tree of `Block` dataclasses (`blocks.py`).
+2. **Layout** (`layout.py`) — Two-pass, order is load-bearing: `resolve_width()` top-down, then `resolve_height()` bottom-up. Width must resolve first because height calls `wrap_text(text, width)`.
+3. **Emit** (`emit.py`) — Walks the block tree and dispatches to renderer functions in `renderers/`.
+
+Entry points:
+- **Library**: `__init__.py:render()` — parse → layout → emit
+- **CLI**: `__main__.py:main()` — argparse with `--width`, `--no-color`, `--check`, `--cjk`, `--tmux`. Exit codes: 0=ok, 1=input, 2=syntax, 3=terminal.
+
+### Renderers (`src/termrender/renderers/`)
+
+Two signatures (not type-enforced):
+- **Leaf**: `render(block, color) -> list[str]` — divider, tree
+- **Container**: `render(block, color, render_child) -> list[str]` — panel, quote, code, columns, callout, table, text, mermaid
+
+`borders.py` is a shared utility, not a renderer. Its `render_box(content_lines, width, ...)` takes **total** width (including borders), not content width.
+
+### Style (`style.py`)
+
+`visual_len()` measures display width accounting for ANSI escapes, emoji, CJK, and combining marks. `wrap_text()` uses `len()` internally (known bug: CJK overflow). `_ambiguous_width` is global mutable state with no reset path — set via `set_ambiguous_width()` or `TERMRENDER_CJK` env var.
+
+## Conventions
+
+- **Commits**: conventional commits (`feat:`, `fix:`, `chore:`, etc.). `feat` → minor, `fix`/`perf` → patch. Auto-released via python-semantic-release on main.
+- **Version**: derived from git tags via hatch-vcs (no version in pyproject.toml).
+- **Python**: 3.10+.
+
+## Supplementary CLAUDE.md files
+
+- `src/termrender/CLAUDE.md` — parser, layout, mermaid, nesting, and `--check`/`--tmux` implementation gotchas
+- `src/termrender/renderers/CLAUDE.md` — renderer contracts, `render_box` width semantics, EAW edge cases
+
+Read these before modifying layout, parsing, or renderer code.

{termrender-0.2.1 → termrender-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 0.2.1
+Version: 0.4.0
 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.4.0/src/termrender/CLAUDE.md

@@ -0,0 +1,59 @@
+# termrender/src/termrender
+
+## Layout: two-pass order is mandatory
+
+`layout.py` runs `resolve_width()` then `resolve_height()` — this order is load-bearing. Height resolution calls `wrap_text(text, width)`, so every block must have `.width` set first. Reversing the order causes `block.width = None`, which silently falls back to `width = 1` (layout.py:77), drastically underestimating all heights.
+
+## Mermaid: subprocess runs in layout, not in the renderer
+
+`layout.py:119–134` runs `mermaid-ascii` and caches the result in `block.attrs["_rendered"]`. The `mermaid` renderer (renderers/mermaid.py) reads this cache key; if it's absent, it runs the subprocess again. A failed layout subprocess (tool missing, timeout) silently stores the raw source diagram in `_rendered`, so the renderer falls back to printing source — no error is raised. Both sites have a 30s timeout.
+
+`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
+
+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.
+
+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`).
+
+## `--check` validates parse only, not layout
+
+`__main__.py` `--check` calls `parse()` directly and exits — it never runs `layout.py`. Layout-time failures (mermaid subprocess missing, column percent overflow, `resolve_width`/`resolve_height` exceptions) pass `--check` cleanly but crash at render time. Use `--check` to catch directive syntax errors, not to guarantee a successful render.
+
+## `_ambiguous_width` is global mutable state; `TERMRENDER_CJK` makes it permanent
+
+`style.set_ambiguous_width(n)` (style.py:21–23) changes East Asian ambiguous-width measurement for the entire process with no reset function. The CLI `--cjk` flag sets `os.environ["TERMRENDER_CJK"]` rather than calling the function directly, so it persists for the entire process. `__init__.py:30–31` calls `set_ambiguous_width(2)` on every `render()` call when the env var is set — but since there's no reset, a single call in any render context permanently widens ambiguous-width for all subsequent renders in the same process. Affects `visual_len()` and therefore all wrapping and column math.
+
+## Column width: explicit widths exceeding available space truncate auto-columns to 1
+
+`layout.py:30–63`: explicit column widths (percent or absolute) are allocated first; remaining space is split among auto-width columns with `max(remaining, 0)`. Two columns each claiming 80% of a 100px terminal leaves auto-width columns with width 1 — no error, no proportional scaling.
+
+## Height calculations with hidden assumptions
+
+- **QUOTE** (layout.py:138): height gets `+1` only when the `author` or `by` attr is set. Using any other key (`attribution`, `source`) silently omits the extra line — the renderer's attribution line is clipped.
+- **TABLE** (layout.py:117): `height = len(rows) + 4` where `rows` includes the header row. The code comment mis-describes this as 5 structural parts; `rows[0]` is the header. Adding a footer or subtitle row needs `+5`, not `+4+1`.
+- **LIST_ITEM** (layout.py:107): text wraps at `max(width - 2, 1)`, hardcoding a 2-column indent. If the renderer changes the indent width, layout height and actual render height diverge silently.
+
+## Character offset tracking across wrapped lines
+
+`text.py:32–33`: after rendering each wrapped line, the offset advances by the line's length and then skips one character if the next character in the original plain text is a space (the space `wrap_text` consumed). If wrapping preserves trailing spaces, this skip is wrong and subsequent span styling shifts by one character.
+
+## `wrap_text` measures in characters, not visual columns
+
+`style.py:195–241`: all line-length comparisons inside `wrap_text` use `len()` (character count), not `visual_len()`. A 2-column-wide CJK character is counted as 1 column-unit, so wrapped lines silently overflow their allocated width by one cell per wide character. This affects every block type that calls `wrap_text`.
+
+## Unknown directive names silently become PANEL
+
+`parser.py:339`: `_DIRECTIVE_TO_BLOCK.get(name, BlockType.PANEL)` — any unrecognized `:::name` becomes a bordered PANEL block with no error or warning. Typos in directive names (e.g. `:::callOut`) produce visible output that looks correct but lacks the expected behavior (callout type, icon, color).
+
+## `--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`.
+
+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.
+
+## `_EMOJI_WIDE_RANGES` must stay sorted by codepoint
+
+`_char_width()` (style.py:144) exits the range scan early on `cp < lo`, assuming all ranges are in ascending codepoint order. Adding a new range out of order causes the early exit to skip ranges with higher `lo` values, silently misclassifying those codepoints as 1-wide.

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/__main__.py

@@ -158,8 +158,25 @@ def main() -> None:
     if args.cjk:
         os.environ["TERMRENDER_CJK"] = "1"
 
-    # --tmux: render in a new tmux side pane
+    # --tmux: render in a new tmux side pane, sized to fit
     if args.tmux:
+        # Validate syntax before creating pane — fail fast to caller's terminal
+        try:
+            from termrender.parser import parse as _parse
+            _parse(source)
+        except DirectiveError as e:
+            _error(
+                f"syntax error: {e}",
+                fix="check directive openers have matching ::: closers and attribute syntax is key=\"value\"",
+                code=EXIT_SYNTAX,
+            )
+        except ValueError as e:
+            _error(
+                f"nesting error: {e}",
+                fix="reduce directive nesting depth (max 50 levels)",
+                code=EXIT_SYNTAX,
+            )
+
         import shlex
         import subprocess
         import tempfile
@@ -168,7 +185,35 @@ def main() -> None:
             _error("not inside a tmux session",
                    fix="run inside tmux or omit --tmux")
 
-        # Save source so the new pane can render it with its own width
+        # Determine desired pane width
+        if args.width:
+            pane_width = args.width
+        else:
+            # Preview render to measure content width
+            from termrender.style import visual_len
+            try:
+                preview = render(source, width=80, color=False)
+                max_w = max(
+                    (visual_len(line) for line in preview.split('\n') if line),
+                    default=40,
+                )
+                pane_width = max(max_w, 40)
+            except Exception:
+                pane_width = 80
+
+        # Cap to available tmux space (leave room for the source pane)
+        try:
+            result = subprocess.run(
+                ["tmux", "display-message", "-p", "#{pane_width}"],
+                capture_output=True, text=True, check=True,
+            )
+            available = int(result.stdout.strip())
+            pane_width = min(pane_width, available - 10)
+        except Exception:
+            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:
@@ -181,14 +226,14 @@ def main() -> None:
             cmd_parts.append("--no-color")
         if args.cjk:
             cmd_parts.append("--cjk")
-        if args.width:
-            cmd_parts.extend(["-w", str(args.width)])
+        cmd_parts.extend(["-w", str(pane_width)])
 
-        pane_cmd = " ".join(cmd_parts) + " | less -R; rm -f " + shlex.quote(tmpfile)
+        # 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)
 
         try:
             subprocess.run(
-                ["tmux", "split-window", "-h", pane_cmd],
+                ["tmux", "split-window", "-h", "-f", "-l", str(pane_width), pane_cmd],
                 check=True,
             )
         except FileNotFoundError:
@@ -222,7 +267,10 @@ def main() -> None:
         sys.exit(EXIT_OK)
 
     try:
-        output = render(source, width=args.width, color=not args.no_color)
+        use_color = not args.no_color and (
+            sys.stdout.isatty() or os.environ.get("TERMRENDER_COLOR") == "1"
+        )
+        output = render(source, width=args.width, color=use_color)
     except TerminalError as e:
         _error(
             f"terminal error: {e}",

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/layout.py

@@ -113,15 +113,37 @@ def resolve_height(block: Block) -> None:
         block.height = len(source.split("\n")) if source else 1
 
     elif bt == BlockType.TABLE:
+        headers = block.attrs.get("headers", [])
         rows = block.attrs.get("rows", [])
-        block.height = len(rows) + 4  # top border + header + separator + data rows + bottom border
+        n_cols = max(len(headers), max((len(r) for r in rows), default=0))
+        if n_cols == 0:
+            block.height = 0
+        else:
+            rh = [_plain_text(headers[i]) if i < len(headers) else "" for i in range(n_cols)]
+            rr = [[_plain_text(row[i]) if i < len(row) else "" for i in range(n_cols)] for row in rows]
+            col_widths = [
+                max(3, visual_len(rh[i]), *(visual_len(r[i]) for r in rr))
+                for i in range(n_cols)
+            ]
+            total = sum(col_widths) + n_cols * 2 + (n_cols + 1)
+            if total > width:
+                avail = max(width - n_cols * 2 - (n_cols + 1), n_cols * 3)
+                total_natural = sum(col_widths)
+                if total_natural > 0:
+                    col_widths = [max(3, round(cw / total_natural * avail)) for cw in col_widths]
+            header_h = max(len(wrap_text(rh[i], col_widths[i])) for i in range(n_cols))
+            data_h = sum(
+                max(len(wrap_text(r[i], col_widths[i])) for i in range(n_cols))
+                for r in rr
+            ) if rr else 0
+            block.height = header_h + data_h + 3  # top border + header sep + bottom border
 
     elif bt == BlockType.MERMAID:
         source = block.attrs.get("source", "") or _plain_text(block.text)
         rendered = source  # fallback
         try:
             result = subprocess.run(
-                ["mermaid-ascii", "-f", "-"],
+                ["mermaid-ascii", "-f", "-", "-w", str(block.width or 80), "-y", "1"],
                 input=source,
                 capture_output=True,
                 text=True,

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/parser.py

@@ -36,12 +36,12 @@ def _sanitize_text(text: str) -> str:
     """Strip non-SGR ANSI escape sequences from text."""
     return _UNSAFE_ANSI_RE.sub('', text)
 
-# Directive opener: :::name or :::name{attrs}
+# Directive opener: :::name or ::::name etc. (3+ colons)
 _DIRECTIVE_OPEN = re.compile(
-    r"^:::(\w+)(?:\{([^}]*)\})?\s*$"
+    r"^(:{3,})(\w+)(?:\{([^}]*)\})?\s*$"
 )
-# Directive closer: exactly ::: on its own line
-_DIRECTIVE_CLOSE = re.compile(r"^:::\s*$")
+# Directive closer: 3+ colons on its own line
+_DIRECTIVE_CLOSE = re.compile(r"^(:{3,})\s*$")
 
 # Attribute parser: key=value or key="quoted value"
 _ATTR_PAIR = re.compile(
@@ -61,6 +61,14 @@ _DIRECTIVE_TO_BLOCK: dict[str, BlockType] = {
 
 _SELF_CLOSING_DIRECTIVES = frozenset({"divider"})
 
+# MyST backtick fence directive: ```{name} optional-argument
+_BACKTICK_DIRECTIVE_RE = re.compile(r"^\{(\w[\w-]*)\}(.*)")
+
+# MyST option line: :key: value — intentionally requires a value after the key
+# (the \s+(.+) part). Flag-style options like :nosandbox: (no value) won't match
+# and will be treated as body content.
+_OPTION_LINE_RE = re.compile(r"^:(\w[\w-]*):\s+(.+)$")
+
 _mistune_md = mistune.create_markdown(renderer="ast", plugins=["table"])
 
 
@@ -71,7 +79,7 @@ def _any_self_closing_before(lines: list[str], close_idx: int) -> bool:
         if not line:
             continue
         m = _DIRECTIVE_OPEN.match(lines[j])
-        if m and m.group(1) in _SELF_CLOSING_DIRECTIVES:
+        if m and m.group(2) in _SELF_CLOSING_DIRECTIVES:
             return True
         return False
     return False
@@ -117,7 +125,40 @@ def _convert_inline(nodes: list[dict]) -> list[InlineSpan]:
     return spans
 
 
-def _convert_ast(nodes: list[dict]) -> list[Block]:
+def _strip_options(body: str) -> tuple[dict[str, str], str]:
+    """Strip MyST option lines from the start of a directive body.
+
+    Option lines have the form `:key: value` and appear at the start of the body.
+    Blank lines between option lines are allowed. Scanning stops at the first
+    non-option, non-blank line.
+
+    Returns (options_dict, remaining_body).
+    """
+    if not body or not body.lstrip("\n").startswith(":"):
+        return {}, body
+    lines = body.split("\n")
+    options: dict[str, str] = {}
+    last_option_idx = -1
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped:
+            # blank lines are OK between options
+            continue
+        m = _OPTION_LINE_RE.match(stripped)
+        if m:
+            options[m.group(1)] = m.group(2)
+            last_option_idx = i
+        else:
+            break
+    if last_option_idx == -1:
+        return {}, body
+    remaining = "\n".join(lines[last_option_idx + 1:])
+    # Strip leading blank lines from remaining body
+    remaining = remaining.lstrip("\n")
+    return options, remaining
+
+
+def _convert_ast(nodes: list[dict], _depth: int = 0) -> list[Block]:
     """Convert mistune AST nodes into Block tree."""
     blocks: list[Block] = []
     for node in nodes:
@@ -142,7 +183,24 @@ def _convert_ast(nodes: list[dict]) -> list[Block]:
         elif ntype == "block_code":
             raw = node.get("raw", "")
             info = node.get("attrs", {}).get("info", "")
-            if info == "mermaid":
+            # MyST backtick fence directive: ```{name} optional-arg
+            m_directive = _BACKTICK_DIRECTIVE_RE.match(info) if info else None
+            if m_directive:
+                dir_name = m_directive.group(1)
+                arg_text = m_directive.group(2).strip()
+                if dir_name == "mermaid":
+                    options, body = _strip_options(raw)
+                    attrs = dict(options)
+                    if arg_text:
+                        attrs["argument"] = arg_text
+                    attrs["source"] = body
+                    blocks.append(Block(type=BlockType.MERMAID, attrs=attrs))
+                else:
+                    attrs: dict[str, Any] = {}
+                    if arg_text:
+                        attrs["argument"] = arg_text
+                    blocks.append(_directive_to_block(dir_name, attrs, raw, _depth=_depth))
+            elif info == "mermaid":
                 blocks.append(Block(
                     type=BlockType.MERMAID,
                     attrs={"source": raw},
@@ -166,7 +224,7 @@ def _convert_ast(nodes: list[dict]) -> list[Block]:
                         if child["type"] == "block_text":
                             item_spans.extend(_convert_inline(child.get("children", [])))
                         else:
-                            sub_blocks.extend(_convert_ast([child]))
+                            sub_blocks.extend(_convert_ast([child], _depth=_depth))
                     items.append(Block(
                         type=BlockType.LIST_ITEM,
                         text=item_spans,
@@ -209,23 +267,23 @@ def _convert_ast(nodes: list[dict]) -> list[Block]:
             blocks.append(Block(type=BlockType.DIVIDER))
 
         elif ntype == "block_quote":
-            children = _convert_ast(node.get("children", []))
+            children = _convert_ast(node.get("children", []), _depth=_depth)
             blocks.append(Block(type=BlockType.QUOTE, children=children))
 
         else:
             # Unknown block type - try to extract any content
             if "children" in node:
-                blocks.extend(_convert_ast(node["children"]))
+                blocks.extend(_convert_ast(node["children"], _depth=_depth))
 
     return blocks
 
 
-def _parse_markdown(source: str) -> list[Block]:
+def _parse_markdown(source: str, _depth: int = 0) -> list[Block]:
     """Parse a markdown string via mistune and convert to Block list."""
     if not source.strip():
         return []
     ast_nodes = _mistune_md(source)
-    return _convert_ast(ast_nodes)
+    return _convert_ast(ast_nodes, _depth=_depth)
 
 
 def _split_directives(source: str) -> list[dict]:
@@ -247,6 +305,9 @@ def _split_directives(source: str) -> list[dict]:
         # Check for directive opener
         m_open = _DIRECTIVE_OPEN.match(line)
         if m_open:
+            colons = m_open.group(1)
+            name = m_open.group(2)
+            attrs_raw = m_open.group(3)
             if not stack:
                 # Top-level directive opening — flush accumulated markdown
                 if current_md_lines:
@@ -256,13 +317,14 @@ def _split_directives(source: str) -> list[dict]:
                     })
                     current_md_lines = []
                 entry = {
-                    "name": m_open.group(1),
-                    "attrs_raw": m_open.group(2),
+                    "name": name,
+                    "attrs_raw": attrs_raw,
                     "body_lines": [],
                     "depth": 1,
+                    "colon_count": len(colons),
                 }
                 # Self-closing directives (no body content expected)
-                if entry["name"] in ("divider",):
+                if entry["name"] in _SELF_CLOSING_DIRECTIVES:
                     segments.append({
                         "type": "directive",
                         "name": entry["name"],
@@ -272,8 +334,9 @@ def _split_directives(source: str) -> list[dict]:
                 else:
                     stack.append(entry)
             else:
-                # Nested directive — track depth and include line in body
-                stack[-1]["depth"] += 1
+                # Nested directive — track depth only if colon count matches
+                if len(colons) == stack[-1]["colon_count"]:
+                    stack[-1]["depth"] += 1
                 stack[-1]["body_lines"].append(line)
             i += 1
             continue
@@ -282,15 +345,20 @@ def _split_directives(source: str) -> list[dict]:
         m_close = _DIRECTIVE_CLOSE.match(line)
         if m_close and not stack:
             if not _any_self_closing_before(lines, i):
+                close_colons = m_close.group(1)
                 raise DirectiveError(
-                    f"line {i + 1}: stray ':::' closer with no open directive"
+                    f"line {i + 1}: stray '{close_colons}' closer with no open directive"
                 )
             # Stray closer after a self-closing directive like divider — skip
             i += 1
             continue
         if m_close and stack:
-            if stack[-1]["depth"] > 1:
-                # Closing a nested directive
+            close_colon_count = len(m_close.group(1))
+            if close_colon_count != stack[-1]["colon_count"]:
+                # Different colon count — treat as body content
+                stack[-1]["body_lines"].append(line)
+            elif stack[-1]["depth"] > 1:
+                # Closing a nested directive with same colon count
                 stack[-1]["depth"] -= 1
                 stack[-1]["body_lines"].append(line)
             else:
@@ -322,10 +390,10 @@ def _split_directives(source: str) -> list[dict]:
     # If stack is not empty, the source has unclosed directives
     if stack:
         unclosed = stack[-1]
-        # Find the line number where this directive was opened
+        colons = ":" * unclosed["colon_count"]
         name = unclosed["name"]
         raise DirectiveError(
-            f"unclosed directive ':::{name}' — missing closing ':::'"
+            f"unclosed directive '{colons}{name}' — missing closing '{colons}'"
         )
 
     return segments
@@ -336,6 +404,12 @@ _MAX_PARSE_DEPTH = 50
 
 def _directive_to_block(name: str, attrs: dict[str, Any], body: str, _depth: int = 0) -> Block:
     """Convert a parsed directive into a Block."""
+    # Strip option lines from body; inline attrs take precedence over options
+    options, body = _strip_options(body)
+    for key, value in options.items():
+        if key not in attrs:
+            attrs[key] = value
+
     block_type = _DIRECTIVE_TO_BLOCK.get(name, BlockType.PANEL)
 
     # Tree and Code directives: store raw body, don't parse as markdown
@@ -368,7 +442,7 @@ def parse(source: str, _depth: int = 0) -> Block:
 
     for seg in segments:
         if seg["type"] == "markdown":
-            children.extend(_parse_markdown(seg["content"]))
+            children.extend(_parse_markdown(seg["content"], _depth=_depth))
         else:
             children.append(_directive_to_block(
                 seg["name"], seg["attrs"], seg["body"], _depth=_depth,

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/renderers/CLAUDE.md

@@ -38,3 +38,17 @@ Attribution line is rendered for `block.attrs["author"]` **or** `block.attrs["by
 
 ## `panel.py` — callouts delegate through a proxy Block
 `render_callout` patches `title`, `color`, and `type=BlockType.PANEL` into a new `Block` instance and calls `render()` on it. The original block is not mutated. The callout type string (`"info"`, `"warning"`, `"error"`, `"success"`) is only used to look up `_CALLOUT_MAP`; an unknown type falls back to blue `ℹ`.
+
+## `mermaid.py` — leaf signature (not container), encoding fix, no returncode check, no truncation
+
+**Leaf signature, not container**: `render(block, color)` — no `render_child`. The parent `CLAUDE.md` incorrectly lists mermaid as a Container renderer.
+
+**`fix_mermaid_encoding`**: `mermaid-ascii` misreads UTF-8 input as Latin-1 and re-encodes, corrupting multi-byte characters (e.g. `→` becomes `â\x86\x92`). The fix is `text.encode("latin-1").decode("utf-8")`; on failure it silently returns the corrupted string — callers cannot distinguish fixed vs. corrupt output.
+
+**`except Exception` swallows everything**: timeout, missing tool, `MemoryError` — all fall back to `rendered = source` (the raw mermaid source text) silently. Returncode is also never checked; a non-zero exit still reads `result.stdout`, producing a blank-line block if stdout was empty. If both `_rendered` and `source` are absent, empty string is sent to `mermaid-ascii`.
+
+**`visual_ljust` pads but never truncates**: every output line is padded to `block.width`. Lines wider than `block.width` overflow without clipping. If `mermaid-ascii` emits a diagram wider than the allocated block, it silently exceeds the layout boundary.
+
+**Trailing blank line**: `rendered.split("\n")` on output ending with `\n` (typical subprocess output) produces a trailing empty string, which becomes a `block.width`-wide blank line appended to every mermaid block.
+
+Layout pre-renders into `block.attrs["_rendered"]` (see `src/termrender/CLAUDE.md`); this renderer re-runs the subprocess only when that key is absent.

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/renderers/borders.py

@@ -11,6 +11,7 @@ def render_box(
     color: bool,
     title: str | None = None,
     border_color: str | None = None,
+    title_color: str | None = None,
     dim: bool = False,
 ) -> list[str]:
     """Render content lines inside a box-drawing border.
@@ -21,6 +22,7 @@ def render_box(
         color: Whether ANSI styling is enabled.
         title: Optional title to display in the top border.
         border_color: Color name for the border (used by panels).
+        title_color: Color for the title text (defaults to border_color).
         dim: Whether to dim the border (used by code blocks).
     """
     # Calculate border character widths dynamically
@@ -46,11 +48,19 @@ def render_box(
         title_visual = visual_len(title_part)
         remaining = inner_w - title_visual
         fill_count = max(0, remaining // dash_v)
-        top_raw = "┌" + title_part + "─" * fill_count + "┐"
+        if title_color and color:
+            # Style title text separately from border chrome
+            styled_title = style(title, color=title_color, bold=True)
+            border_prefix = style("┌─ ", **style_kw)
+            border_suffix = style(" " + "─" * fill_count + "┐", **style_kw)
+            top = border_prefix + styled_title + border_suffix
+        else:
+            top_raw = "┌" + title_part + "─" * fill_count + "┐"
+            top = style(top_raw, **style_kw)
     else:
         fill_count = max(0, inner_w // dash_v)
         top_raw = "┌" + "─" * fill_count + "┐"
-    top = style(top_raw, **style_kw)
+        top = style(top_raw, **style_kw)
     top = visual_ljust(top, width)
 
     # Bottom border

{termrender-0.2.1 → termrender-0.4.0}/src/termrender/renderers/mermaid.py

@@ -31,7 +31,7 @@ def render(block: Block, color: bool) -> list[str]:
         source = block.attrs.get("source", "")
         try:
             result = subprocess.run(
-                ["mermaid-ascii", "-f", "-"],
+                ["mermaid-ascii", "-f", "-", "-w", str(block.width or 80), "-y", "1"],
                 input=source,
                 capture_output=True,
                 text=True,