pi-syntax-highlight 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,32 @@
3
3
  All notable changes to this project are documented in this file. The format
4
4
  follows Keep a Changelog, and this project uses semantic versioning.
5
5
 
6
+ ## [0.1.1] - 2026-10-26
7
+
8
+ ### Added
9
+
10
+ - `assets/icon.svg` (source) and `assets/icon.png` (1200x750, the same canvas
11
+ `pi-simple-agents` uses) as the gallery preview. The detail thumbnail crops the
12
+ height to 16/9, so the terminal window sits inside the central area and no edge
13
+ of it is cut.
14
+ - `DEVELOPER.md`: module map, theme handling and cache invalidation, the rules
15
+ the markdown transformer follows, what the hook cannot reach, and the tests.
16
+
17
+ ### Changed
18
+
19
+ - Package metadata. `license: "MIT"` added: without the field npm published the
20
+ package as Proprietary while the README claimed MIT. `description` rewritten
21
+ for npm search, `keywords` grown from `pi-package` alone to also cover
22
+ `pi-extension`, `syntax-highlighting`, `markdown`, `code-fences`,
23
+ `language-detection`, `tui`, `diff` and `tool-output`, and `pi.image` points at
24
+ the raw icon.
25
+ - README rewritten for the pi.dev audience: install first, one or two sentences
26
+ per renderer, the limits in user terms, and links to `DEVELOPER.md` and
27
+ `CHANGELOG.md`. The tagline now opens the file with the badges under it,
28
+ because the gallery builds its description from the first README paragraph,
29
+ and the `pi -e` example no longer carries an absolute path from the author's
30
+ machine.
31
+
6
32
  ## [0.1.0] - 2026-10-25
7
33
 
8
34
  ### Added
package/DEVELOPER.md ADDED
@@ -0,0 +1,73 @@
1
+ # pi-syntax-highlight: Developer Guide
2
+
3
+ How the extension draws what it draws, and why a few things stay out of reach. For installation and user-facing behavior, see [README.md](./README.md).
4
+
5
+ Needs Node 24 or newer (the tests run through `--experimental-strip-types`) and pi 1.4 or newer.
6
+
7
+ ## Layout
8
+
9
+ `extensions/index.ts` is the whole public surface: it registers the tool renderers and the two markdown transformers. Everything else under `src/` is internal.
10
+
11
+ - `resolve-renderers.ts` builds the `ToolRenderers` object. One builder per tool, called from a shared wrapper that decides the theme, the error state, and the collapsed preview.
12
+ - `render-*.ts` turn a tool result into the text of a `Text` node: `grep`, `find`, `ls`, `bash`, `read`, `edit`, `write`, and `generic` (codemode, MCP, unknown tools).
13
+ - `render-utils.ts` holds the pieces those builders share: gutters, footers, the expand hint, the truncation notice.
14
+ - `highlight.ts` wraps pi's `highlightCode` with a cache, and `tokens.ts` holds the SGR sequences the code reads directly.
15
+ - `style-path.ts`, `render-path.ts`, `emphasis.ts` handle the small decisions a diff or a path needs: which color a basename gets, where the match sits inside a line, which words changed.
16
+ - `grep-parse.ts` splits grep's `path:line: text` and `path-line- text` forms. `detect-language.ts` answers a language for a fence or a file name.
17
+ - `markdown-fence-lang.ts`, `markdown-style.ts`, `markdown-theme.ts` are the markdown pass: which fence gets a label, which line gets a sequence, which palette the sequences use.
18
+ - `active-theme.ts` keeps the theme object from the last rendered tool result.
19
+
20
+ ## Theme handling
21
+
22
+ The theme reaches the renderers as a proxy of stable identity, so a reference comparison never sees a theme switch. The highlight cache is keyed by the color sequences the highlighter actually reads, which changes when the theme does. `syncHighlightTheme` does the comparison on every render.
23
+
24
+ Tool failure is read from the render context, not from the result: the host passes no `isError` field inside `AgentToolResult`, so a check there is always false and no renderer ever paints an error. `render-generic` and the path renderers both read the context flag.
25
+
26
+ Without an initialized theme the renderers fall back to the plain tool output color. The markdown pass degrades the same way: with no theme captured yet, it emits no sequences at all.
27
+
28
+ ## How the markdown styling works
29
+
30
+ There is no hook for the markdown theme, so the styles are written into the markdown text itself as terminal sequences, through the same transformer that labels fences. Three rules keep that contained:
31
+
32
+ - Only `assistant` messages are touched. In a user message the line background and the preserved backslash escapes would fight the injected sequences; thinking blocks keep their own default style.
33
+ - Every sequence opens and closes inside its line and closes only the attribute it opened, never with a full reset, so the style of the surrounding construct survives the span.
34
+ - The visible text is unchanged: stripping the sequences from the render leaves the same characters as the render without the transformer, except the backtick delimiters of inline code, which the stock renderer drops.
35
+
36
+ The colors come from the theme captured on the last rendered tool result, so a theme switch repaints them. A line that already carries an escape sequence is copied verbatim, which is what keeps a second pass, a Mermaid diagram, or a partially streamed message untouched.
37
+
38
+ Fence labels are chosen by `detect-language.ts`, which never answers `markdown` or `plaintext`, and leaves `mermaid`, `math`, `latex`, and `katex` alone. A fence that already carries a label is never rewritten.
39
+
40
+ ## What stays out of reach
41
+
42
+ `registerMarkdownTransformer` is a display-only `string => string` step applied before parsing. There is no extension hook that replaces the `Markdown` component from `@earendil-works/pi-tui` or its theme, so table layout, list colors, and column alignment are out of reach, and the styling above is the whole of what the hook allows.
43
+
44
+ Three constructs stay out of reach even for that hook:
45
+
46
+ - Fence chrome and the language label. The info string of a fence is the language, so any sequence inside it breaks both the label and the highlighting of the body; a sequence on the closing line stops it from closing.
47
+ - The `│ ` border of a blockquote, which the renderer prepends after wrapping the content.
48
+ - The accent color of a heading stops at its first inline token: the renderer reopens its own heading color around every inline span, so text after `**bold**` or `` `code` `` in the same heading returns to the theme's heading color.
49
+
50
+ ## Known limits
51
+
52
+ - `grep` output whose path itself contains `:N: ` or `-N- ` is inherently ambiguous; pi does not disambiguate it either.
53
+ - Only one markdown transformer is allowed per extension; the pipeline inside this one is a single pass.
54
+ - A `read` body records the line number where each source line starts. A source line longer than the terminal wraps, and the wrapped continuation does not repeat the gutter.
55
+ - The diff of an `edit` marks changed words only where one removed line is followed by one added line, the same rule pi applies; several removed lines keep the per-line colors.
56
+ - Restoring the backticks of an inline code span widens a table cell, so the columns of that table are laid out again.
57
+ - Code spans delimited by more than one backtick, setext headings, and escaped backticks are copied as they are.
58
+
59
+ ## Tests
60
+
61
+ ```bash
62
+ npm install
63
+ npm run typecheck
64
+ npm test
65
+ ```
66
+
67
+ `markdown-render-parity.test.ts` is the guard on the markdown pass: it renders the same message with and without the transformer, strips the sequences, and compares the visible characters. `markdown-pipeline.test.ts` covers the fence labeling pass, `active-theme.test.ts` and `highlight.test.ts` cover the theme cache.
68
+
69
+ To try a working copy without installing it, run `pi -e .` from the package directory.
70
+
71
+ ## License
72
+
73
+ MIT
package/README.md CHANGED
@@ -1,46 +1,52 @@
1
1
  # pi-syntax-highlight
2
2
 
3
- Pi extension that adds syntax highlighting to tool output and to assistant markdown: tool renderers for `grep`, `find`, `ls`, the shells, `read`, `edit` and `write`, and a markdown pass that colors headings, blockquotes and inline code without changing the text.
3
+ Syntax highlighting for what pi prints: tool output first, then the markdown the assistant writes back. Rendering only: tool calls, results and settings stay exactly as they are.
4
4
 
5
- Scope is limited to rendering: no tool behavior, no settings, no other plugins.
5
+ [![npm version](https://badge.fury.io/js/pi-syntax-highlight.svg)](https://badge.fury.io/js/pi-syntax-highlight)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
7
 
7
- ## What it touches
8
+ ## Install
8
9
 
9
- | Tool | Change |
10
- |---|---|
11
- | `grep` | Paths and line numbers styled, matched line content highlighted with the language of the file, match emphasized, truncation footer preserved |
12
- | `find`, `ls` | Directories dimmed with a trailing slash, basenames colored by file family, limit footer preserved |
13
- | `bash`, `powershell` | Completed output styled (diffs, JSON, paths, errors), collapsed preview with the expand hint, duration line |
14
- | `read` | Call header with path and line range; expanded body numbered from the real line the tool read (`offset`), highlighted by file language, continuation and truncation notices in the warning color; a collapsed call stays silent like stock pi |
15
- | `edit` | Diff highlighted by file language, line numbers dimmed, changed words in reverse video; the diff fills the body of the call's box, whose background follows success or failure |
16
- | `write` | Header preview of the content, highlighted and capped while the argument is still arriving, with the stock line footer; failures in the error color |
17
- | `codemode`, MCP tools, unknown tools | Only when the tool has no result renderer of its own: JSON and diff bodies highlighted, anything else in the plain content color, collapsed to 10 lines with the expand hint |
18
- | markdown fences | A fence with no info string gets a detected language injected so the existing highlighter colors it; a fence that already carries a label is never rewritten. Detection never answers `markdown` or `plaintext`, and fences tagged `mermaid`, `math`, `latex`, or `katex` are left untouched |
19
- | assistant markdown | Headings in the theme's accent color with one attribute per level, inline code with its backtick delimiters visible, and blockquote text in the accent color |
10
+ ```bash
11
+ pi install npm:pi-syntax-highlight
12
+ ```
20
13
 
21
- ## How the markdown styling works
14
+ Start a new session and the colors are on. To try it without installing:
22
15
 
23
- There is no hook for the markdown theme, so the styles are written into the markdown text itself as terminal sequences, through the same transformer that labels fences. Three rules keep that contained:
16
+ ```bash
17
+ pi -e npm:pi-syntax-highlight
18
+ ```
24
19
 
25
- - Only `assistant` messages are touched. In a user message the line background and the preserved backslash escapes would fight the injected sequences; thinking blocks keep their own default style.
26
- - Every sequence opens and closes inside its line and closes only the attribute it opened, never with a full reset, so the style of the surrounding construct survives the span.
27
- - The visible text is unchanged: stripping the sequences from the render leaves the same characters as the render without the transformer, except the backtick delimiters of inline code, which the stock renderer drops.
20
+ Needs pi 1.4 or newer. Node 24 or newer matters only for running the working copy, not for the install.
28
21
 
29
- The colors come from the theme captured on the last rendered tool result, so a theme switch repaints them; a line that already carries a sequence is copied verbatim, which is what keeps a second pass, a Mermaid diagram, or a partially streamed message untouched.
22
+ ## What gets colored
30
23
 
31
- ## What it cannot do
24
+ | Tool | What you see |
25
+ |---|---|
26
+ | `grep` | Paths and line numbers styled, each matched line highlighted in the language of its file, the match itself emphasized. The truncation footer stays. |
27
+ | `find`, `ls` | Directories dimmed with a trailing slash, basenames colored by file family. The limit footer stays. |
28
+ | `bash`, `powershell` | Finished output styled: diffs, JSON, paths, errors. A collapsed call shows its opening lines, the expand hint, and the duration. |
29
+ | `read` | Line numbers count from the offset the read started at, not from 1, and the body is highlighted by file language. A collapsed read stays silent, the way stock pi leaves it. |
30
+ | `edit` | The diff is highlighted by file language, line numbers dimmed, changed words in reverse video. A failure paints the body in the error color. |
31
+ | `write` | The header previews the content while it streams, highlighted and capped, with the stock line footer. |
32
+ | `codemode`, MCP tools, unknown tools | Applies only where the tool has no renderer of its own. JSON and diff bodies get highlighted, anything else keeps the plain content color, and the body collapses to 10 lines with the expand hint. |
33
+ | Markdown fences | A fence with no label gets a detected language, so the block comes out colored. A fence that already carries a label is never rewritten, and `mermaid`, `math`, `latex` and `katex` are left alone. |
34
+ | Assistant markdown | Headings, blockquotes and inline code, described below. |
32
35
 
33
- `registerMarkdownTransformer` is a display-only `string => string` step applied before parsing. There is no extension hook that replaces the `Markdown` component from `@earendil-works/pi-tui` or its theme, so table layout, list colors, and column alignment are out of reach, and the markdown styling above is the whole of what the hook allows.
36
+ ## Markdown styling
34
37
 
35
- Three constructs stay out of reach even for that hook:
38
+ Headings take the theme's accent color, with one extra attribute per level so the levels stay apart; blockquote text takes the accent color too, and inline code shows its backticks again. Nothing else in the message moves, so the text reads the same once the colors are stripped.
36
39
 
37
- - Fence chrome and the language label. The info string of a fence *is* the language, so any sequence inside it breaks both the label and the highlighting of the body; a sequence on the closing line stops it from closing.
38
- - The `│ ` border of a blockquote, which the renderer prepends after wrapping the content.
39
- - The accent color of a heading stops at its first inline token: the renderer reopens its own heading color around every inline span, so text after `**bold**` or `` `code` `` in the same heading returns to the theme's heading color.
40
+ ## Limits
40
41
 
41
- ## Development
42
+ - A `grep` output whose own path contains `:N: ` is ambiguous, and pi does not disambiguate it either.
43
+ - No initialized theme, no color: every renderer falls back to plain tool output, and the markdown pass writes nothing.
44
+ - The accent color of a heading stops at its first inline token, so text after `**bold**` or `` `code` `` in the same heading returns to the theme heading color.
45
+ - Fence labels and fence chrome stay unstyled, and so does the `│` border of a blockquote.
46
+ - Getting the backticks back widens an inline code span, so the columns of a table that holds one are laid out again.
47
+ - Code spans with more than one backtick, setext headings, and escaped backticks are copied as they are.
42
48
 
43
- Requires Node 24+ and pi 1.4+.
49
+ ## Development
44
50
 
45
51
  ```bash
46
52
  npm install
@@ -48,21 +54,12 @@ npm run typecheck
48
54
  npm test
49
55
  ```
50
56
 
51
- Load it into a session without installing:
52
-
53
- ```bash
54
- pi -e /home/pablo/LLMs/pi-syntax-highlight/extensions/index.ts
55
- ```
57
+ Load the working copy from the package directory with `pi -e .`.
56
58
 
57
- ## Known limitations
59
+ ## More
58
60
 
59
- - `grep` output whose path itself contains `:N: ` or `-N- ` is inherently ambiguous; pi does not disambiguate it either.
60
- - Highlighting relies on pi's `highlightCode`, which uses the active theme; without an initialized theme the renderers fall back to plain tool output color. The markdown styling degrades the same way: with no theme captured yet it emits no sequences.
61
- - Only one markdown transformer is allowed per extension; the pipeline inside this one is a single pass.
62
- - A `read` body records the line number where each source line starts. A source line longer than the terminal wraps, and the wrapped continuation does not repeat the gutter.
63
- - The diff of an `edit` marks changed words only where one removed line is followed by one added line, the same rule pi applies; several removed lines keep the per-line colors.
64
- - Restoring the backticks of an inline code span widens a table cell, so the columns of that table are laid out again.
65
- - Code spans delimited by more than one backtick, setext headings, and escaped backticks are copied as they are.
61
+ - [DEVELOPER.md](DEVELOPER.md): how the renderers and the markdown pass are built, and the tests.
62
+ - [CHANGELOG.md](CHANGELOG.md): what changed in each release.
66
63
 
67
64
  ## License
68
65
 
Binary file
@@ -0,0 +1,36 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="750" viewBox="0 0 1200 750">
2
+ <rect width="1200" height="750" fill="#0E1726"/>
3
+ <circle cx="600" cy="375" r="420" fill="#12202F"/>
4
+ <!-- terminal window -->
5
+ <rect x="286" y="146" width="628" height="458" rx="28" fill="#0B1220" stroke="#2F7C93" stroke-width="14"/>
6
+ <line x1="286" y1="222" x2="914" y2="222" stroke="#2F7C93" stroke-width="12"/>
7
+ <g fill="#19C7D4">
8
+ <circle cx="340" cy="184" r="14"/>
9
+ <circle cx="388" cy="184" r="14" fill="#2F7C93"/>
10
+ <circle cx="436" cy="184" r="14" fill="#2F7C93"/>
11
+ </g>
12
+ <!-- one highlighted line -->
13
+ <rect x="308" y="356" width="584" height="52" rx="10" fill="#19C7D4" opacity="0.16"/>
14
+ <rect x="308" y="356" width="6" height="52" rx="3" fill="#19C7D4"/>
15
+ <!-- code, one bar per token -->
16
+ <g rx="8">
17
+ <rect x="340" y="264" width="104" height="26" rx="13" fill="#C792EA"/>
18
+ <rect x="458" y="264" width="196" height="26" rx="13" fill="#82AAFF"/>
19
+ <rect x="668" y="264" width="164" height="26" rx="13" fill="#A5E075"/>
20
+ <rect x="392" y="312" width="86" height="26" rx="13" fill="#F78C6C"/>
21
+ <rect x="492" y="312" width="238" height="26" rx="13" fill="#D6DEEB"/>
22
+ <rect x="340" y="370" width="72" height="26" rx="13" fill="#82AAFF"/>
23
+ <rect x="426" y="370" width="150" height="26" rx="13" fill="#A5E075"/>
24
+ <rect x="590" y="370" width="112" height="26" rx="13" fill="#C792EA"/>
25
+ <rect x="392" y="426" width="196" height="26" rx="13" fill="#D6DEEB"/>
26
+ <rect x="602" y="426" width="84" height="26" rx="13" fill="#F78C6C"/>
27
+ <rect x="340" y="484" width="58" height="26" rx="13" fill="#19C7D4"/>
28
+ <rect x="412" y="484" width="148" height="26" rx="13" fill="#D6DEEB"/>
29
+ <rect x="574" y="484" width="96" height="26" rx="13" fill="#A5E075"/>
30
+ <rect x="684" y="484" width="120" height="26" rx="13" fill="#2F7C93"/>
31
+ <rect x="340" y="542" width="96" height="26" rx="13" fill="#2F7C93"/>
32
+ <rect x="450" y="542" width="64" height="26" rx="13" fill="#C792EA"/>
33
+ </g>
34
+ <!-- caret at the end of the last line -->
35
+ <rect x="530" y="532" width="16" height="46" fill="#19C7D4"/>
36
+ </svg>
package/package.json CHANGED
@@ -1,17 +1,31 @@
1
1
  {
2
2
  "name": "pi-syntax-highlight",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "private": false,
5
- "description": "Syntax highlighting for pi tool output (grep, find, ls, bash, read, edit, write) and for assistant markdown (headings, blockquotes, inline code), plus language detection for unlabeled markdown fences.",
5
+ "description": "Syntax highlighting for pi: colors tool output (grep, find, ls, bash, read, edit, write), diffs, JSON and assistant markdown, and detects the language of unlabeled code fences.",
6
+ "license": "MIT",
6
7
  "repository": {
7
8
  "type": "git",
8
9
  "url": "git+https://github.com/piousp/llm-skills.git",
9
10
  "directory": "pi-syntax-highlight"
10
11
  },
11
12
  "keywords": [
12
- "pi-package"
13
+ "pi-package",
14
+ "pi-extension",
15
+ "pi",
16
+ "syntax-highlighting",
17
+ "highlighting",
18
+ "markdown",
19
+ "code-fences",
20
+ "language-detection",
21
+ "terminal",
22
+ "tui",
23
+ "diff",
24
+ "tool-output",
25
+ "theme"
13
26
  ],
14
27
  "pi": {
28
+ "image": "https://raw.githubusercontent.com/piousp/llm-skills/main/pi-syntax-highlight/assets/icon.png",
15
29
  "extensions": [
16
30
  "./extensions"
17
31
  ]