pi-syntax-highlight 0.0.0-stage → 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.
Files changed (52) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/DEVELOPER.md +73 -0
  3. package/README.md +65 -2
  4. package/assets/icon.png +0 -0
  5. package/assets/icon.svg +36 -0
  6. package/extensions/index.ts +22 -0
  7. package/package.json +49 -4
  8. package/src/active-theme.ts +26 -0
  9. package/src/detect-language.ts +294 -0
  10. package/src/emphasis.ts +160 -0
  11. package/src/grep-parse.ts +42 -0
  12. package/src/highlight.ts +109 -0
  13. package/src/markdown-fence-lang.ts +180 -0
  14. package/src/markdown-style.ts +134 -0
  15. package/src/markdown-theme.ts +53 -0
  16. package/src/render-bash.ts +180 -0
  17. package/src/render-edit.ts +207 -0
  18. package/src/render-find.ts +64 -0
  19. package/src/render-generic.ts +86 -0
  20. package/src/render-grep.ts +142 -0
  21. package/src/render-ls.ts +66 -0
  22. package/src/render-path.ts +54 -0
  23. package/src/render-read.ts +277 -0
  24. package/src/render-utils.ts +219 -0
  25. package/src/render-write.ts +81 -0
  26. package/src/resolve-renderers.ts +406 -0
  27. package/src/style-path.ts +48 -0
  28. package/src/tokens.ts +114 -0
  29. package/test/unit/active-theme.test.ts +38 -0
  30. package/test/unit/bash-preview.test.ts +57 -0
  31. package/test/unit/detect-language.test.ts +124 -0
  32. package/test/unit/emphasis.test.ts +113 -0
  33. package/test/unit/extensions-index.test.ts +116 -0
  34. package/test/unit/grep-parse.test.ts +125 -0
  35. package/test/unit/highlight.test.ts +107 -0
  36. package/test/unit/markdown-fence-lang.test.ts +131 -0
  37. package/test/unit/markdown-pipeline.test.ts +153 -0
  38. package/test/unit/markdown-render-parity.test.ts +127 -0
  39. package/test/unit/markdown-style.test.ts +152 -0
  40. package/test/unit/markdown-theme.test.ts +86 -0
  41. package/test/unit/render-bash.test.ts +194 -0
  42. package/test/unit/render-edit.test.ts +214 -0
  43. package/test/unit/render-find.test.ts +139 -0
  44. package/test/unit/render-generic.test.ts +152 -0
  45. package/test/unit/render-grep.test.ts +338 -0
  46. package/test/unit/render-ls.test.ts +132 -0
  47. package/test/unit/render-read.test.ts +375 -0
  48. package/test/unit/render-utils.test.ts +324 -0
  49. package/test/unit/render-write.test.ts +143 -0
  50. package/test/unit/resolve-renderers.test.ts +474 -0
  51. package/test/unit/style-path.test.ts +74 -0
  52. package/tsconfig.json +15 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,86 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file. The format
4
+ follows Keep a Changelog, and this project uses semantic versioning.
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
+
32
+ ## [0.1.0] - 2026-10-25
33
+
34
+ ### Added
35
+
36
+ - `read` result renderer: line-number gutter counted from the line the tool
37
+ actually read, body highlighted by file language, continuation and truncation
38
+ notices in the warning color, stock footer and collapse behavior.
39
+ - `read` and `write` call headers: path with a hyperlink, line range, compact
40
+ header for skills and agent resource files, and a highlighted content preview
41
+ for `write` that is capped while the argument streams.
42
+ - `edit` result renderer: diff highlighted by file language, dimmed line numbers,
43
+ changed words in reverse video, error body in the error color. The diff fills
44
+ the body of the call's own box, so the header keeps its success or failure
45
+ background.
46
+ - Markdown styling for assistant messages: headings in the accent color with one
47
+ attribute per level, inline code with its backtick delimiters restored, and
48
+ blockquote text in the accent color. Sequences close the attribute they opened
49
+ and never cross a line; the visible text is unchanged apart from the restored
50
+ delimiters.
51
+ - `diff` dependency for the word-level highlight of an edited line.
52
+
53
+ ### Changed
54
+
55
+ - `read` numbers its body and lifts the tool's continuation notice out of the
56
+ highlighted text.
57
+ - `edit` no longer paints its diff through pi's `renderDiff`, which reads the
58
+ module-global theme and does not highlight code.
59
+
60
+ ### Fixed
61
+
62
+ - The highlight cache now invalidates on a theme change. The theme object is a
63
+ proxy of stable identity, so comparing references never saw the switch; the
64
+ cache is keyed by the color sequences the highlighter actually reads.
65
+ - Tool failures are detected through the render context. The host passes no
66
+ `isError` inside the result, so the previous check was always false and
67
+ `grep`, `find`, `ls` and the generic overlay never painted an error.
68
+
69
+ ## [0.0.1] - 2026-10-24
70
+
71
+ ### Added
72
+
73
+ - `grep` result renderer: styled paths and line numbers, matched lines
74
+ highlighted with the file's language, match emphasized, truncation footer
75
+ preserved.
76
+ - `find` and `ls` result renderers: dimmed directories, basenames colored by
77
+ file family, limit footer preserved.
78
+ - `bash` and `powershell` result renderers: diffs, JSON, paths and errors
79
+ styled, collapsed preview with the expand hint, duration line.
80
+ - Generic result overlay for `codemode`, MCP and unknown tools that have no
81
+ renderer of their own: JSON and diff bodies highlighted, 10-line collapsed
82
+ preview.
83
+ - Markdown fence transformer: unlabeled fences get a detected language
84
+ injected; labeled fences and `mermaid`, `math`, `latex`, `katex` are left
85
+ untouched.
86
+ - `read`, `write` and `edit` are passed through unchanged.
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,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # pi-syntax-highlight
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+
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)
7
+
8
+ ## Install
9
+
10
+ ```bash
11
+ pi install npm:pi-syntax-highlight
12
+ ```
13
+
14
+ Start a new session and the colors are on. To try it without installing:
15
+
16
+ ```bash
17
+ pi -e npm:pi-syntax-highlight
18
+ ```
19
+
20
+ Needs pi 1.4 or newer. Node 24 or newer matters only for running the working copy, not for the install.
21
+
22
+ ## What gets colored
23
+
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. |
35
+
36
+ ## Markdown styling
37
+
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.
39
+
40
+ ## Limits
41
+
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.
48
+
49
+ ## Development
50
+
51
+ ```bash
52
+ npm install
53
+ npm run typecheck
54
+ npm test
55
+ ```
56
+
57
+ Load the working copy from the package directory with `pi -e .`.
58
+
59
+ ## More
60
+
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.
63
+
64
+ ## License
65
+
66
+ MIT
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>
@@ -0,0 +1,22 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { activeTheme, captureTheme } from "../src/active-theme.ts";
3
+ import { createMarkdownTransformer } from "../src/markdown-fence-lang.ts";
4
+ import { resolveToolRenderers } from "../src/resolve-renderers.ts";
5
+
6
+ /**
7
+ * pi-syntax-highlight entry point.
8
+ *
9
+ * The tool resolver wraps the host chain and overrides only the result slots
10
+ * this package styles; the markdown transformer labels the fences that arrive
11
+ * without a language so the built-in highlighter has a grammar to paint with, and
12
+ * styles headings, blockquotes and inline code spans for the assistant message.
13
+ */
14
+ export default function piSyntaxHighlight(pi: ExtensionAPI): void {
15
+ pi.registerToolRenderer(resolveToolRenderers);
16
+ pi.registerMarkdownTransformer(createMarkdownTransformer({ resolveTheme: activeTheme }));
17
+ // A render slot receives the theme it paints with, but a markdown message does
18
+ // not: `session_start` is the one place the extension is handed one, and the
19
+ // reference it captures keeps resolving against the theme in effect, so no later
20
+ // session event is needed.
21
+ pi.on("session_start", (_event, ctx) => captureTheme(ctx.ui.theme));
22
+ }
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "pi-syntax-highlight",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "private": false,
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",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/piousp/llm-skills.git",
10
+ "directory": "pi-syntax-highlight"
11
+ },
12
+ "keywords": [
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"
26
+ ],
27
+ "pi": {
28
+ "image": "https://raw.githubusercontent.com/piousp/llm-skills/main/pi-syntax-highlight/assets/icon.png",
29
+ "extensions": [
30
+ "./extensions"
31
+ ]
32
+ },
33
+ "type": "module",
34
+ "scripts": {
35
+ "test": "node --experimental-strip-types --test test/unit/*.test.ts",
36
+ "typecheck": "tsc --noEmit -p tsconfig.json",
37
+ "test:types": "npm run typecheck"
38
+ },
39
+ "peerDependencies": {
40
+ "@earendil-works/pi-coding-agent": "*",
41
+ "@earendil-works/pi-tui": "*"
42
+ },
43
+ "dependencies": {
44
+ "diff": "^8.0.4"
45
+ },
46
+ "devDependencies": {
47
+ "@earendil-works/pi-coding-agent": "^1.4.0",
48
+ "@earendil-works/pi-tui": "^1.4.0",
49
+ "typescript": "^7.0.2"
50
+ }
51
+ }
@@ -0,0 +1,26 @@
1
+ import type { Theme } from "@earendil-works/pi-coding-agent";
2
+
3
+ // The `Theme` a renderer receives is a proxy of stable identity whose reads
4
+ // resolve against the theme in effect, so a theme change never swaps the object.
5
+ // Keeping the reference is therefore correct, and anything derived from it (a
6
+ // palette, a cached style, a highlight line) has to be invalidated by value:
7
+ // comparing the reference would never see the change.
8
+ let active: Theme | undefined;
9
+
10
+ // Called by every render slot this package owns, before anything is painted, so
11
+ // the last frame rendered is what the non-renderer paths see afterwards.
12
+ export function captureTheme(theme: Theme): void {
13
+ active = theme;
14
+ }
15
+
16
+ // `undefined` until the first result of a session paints, and again after
17
+ // `resetActiveTheme`; callers degrade to unstyled output instead of throwing.
18
+ export function activeTheme(): Theme | undefined {
19
+ return active;
20
+ }
21
+
22
+ // Tests only: the capture is module state on purpose, and each test starts from
23
+ // the same "no theme seen yet" state instead of inheriting the previous one.
24
+ export function resetActiveTheme(): void {
25
+ active = undefined;
26
+ }