@zenera/view 1.1.26 → 1.1.27
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/README.md +72 -22
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,15 +1,67 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-view-dark.svg">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-view-light.svg" alt="ZENERA VIEW" width="747">
|
|
5
|
+
</picture>
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@zenera/view)
|
|
8
|
+
[](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
|
|
11
|
+
</div>
|
|
12
|
+
|
|
1
13
|
# @zenera/view
|
|
2
14
|
|
|
3
|
-
A live local viewer for a folder. Markdown
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
15
|
+
**A live local viewer for a folder. Markdown with tables and Mermaid diagrams,
|
|
16
|
+
highlighted code, directory listings - redrawn in place as the files change.**
|
|
17
|
+
|
|
18
|
+
> Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). It ships with
|
|
19
|
+
> [`zen`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md)
|
|
20
|
+
> as the `view` **subcommand**, and works just as well as a library on its own.
|
|
21
|
+
|
|
22
|
+
## Why
|
|
23
|
+
|
|
24
|
+
Agents write reports, plans, traces and diagrams to disk, and keep rewriting
|
|
25
|
+
them while they work. `@zenera/view` turns that folder into a page you can leave
|
|
26
|
+
open: every change shows up within a second, with no reload, no lost scroll
|
|
27
|
+
position, and no flicker of diagrams that did not change.
|
|
28
|
+
|
|
29
|
+
- **Markdown as GitHub draws it** - GFM tables, task lists, heading anchors and
|
|
30
|
+
[Mermaid](https://mermaid.js.org) diagrams.
|
|
31
|
+
- **Highlighted code** - `.json`, `.jsonl`, `.py`, `.ts`, `.yaml`, `.patch` and more.
|
|
32
|
+
- **Directories as listings**, so the whole tree is navigable from one page.
|
|
33
|
+
- **Everything else as is** - images, HTML and PDF are handed to the browser.
|
|
34
|
+
- **Live, minimal updates** - only the nodes that changed are repainted.
|
|
35
|
+
- **Local and offline** - loopback only, nothing fetched from the network.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
Node.js 24+, ESM only. It comes with the CLI:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npm i -g @zenera/cli
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
or on its own, as a library:
|
|
8
46
|
|
|
9
47
|
```sh
|
|
10
48
|
npm i @zenera/view
|
|
11
49
|
```
|
|
12
50
|
|
|
51
|
+
## Use
|
|
52
|
+
|
|
53
|
+
### From the command line
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
zen view # this folder
|
|
57
|
+
zen view finetune/STATUS.md --open # one file, opened in the browser
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`zen view` serves until Ctrl-C and prints its address. `--port`, `--throttle`
|
|
61
|
+
and `--hidden` map to the options below; `zen view --help` has the details.
|
|
62
|
+
|
|
63
|
+
### From code
|
|
64
|
+
|
|
13
65
|
```ts
|
|
14
66
|
import { serveView } from '@zenera/view';
|
|
15
67
|
|
|
@@ -19,23 +71,7 @@ console.log(server.url); // http://127.0.0.1:<port>/STATUS.md
|
|
|
19
71
|
await server.close();
|
|
20
72
|
```
|
|
21
73
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
## How it works
|
|
25
|
-
|
|
26
|
-
The server parses each file into a sanitized HTML syntax tree (remark + GFM for
|
|
27
|
-
markdown, lowlight for code) and pushes it to the page over server-sent events -
|
|
28
|
-
on connect, and again whenever the file changes. The page is a small React app
|
|
29
|
-
that turns the tree into elements, so an update repaints only the nodes that
|
|
30
|
-
differ. Mermaid runs in the browser, from the copy installed with this package,
|
|
31
|
-
so nothing is fetched from the network.
|
|
32
|
-
|
|
33
|
-
Files are watched through their directory, so a writer that replaces a file by
|
|
34
|
-
renaming a temporary over it is followed; a slow poll backs up `fs.watch`.
|
|
35
|
-
A file is rendered once per change however many pages show it, and one path is
|
|
36
|
-
pushed at most once per `throttleMs`.
|
|
37
|
-
|
|
38
|
-
## Options
|
|
74
|
+
### Options
|
|
39
75
|
|
|
40
76
|
| option | default | meaning |
|
|
41
77
|
| ------------ | ------------------------------ | ------------------------------------------- |
|
|
@@ -47,6 +83,20 @@ pushed at most once per `throttleMs`.
|
|
|
47
83
|
| `maxClients` | 64 | pages open at once |
|
|
48
84
|
| `throttleMs` | 1000 | least time between two pushes of one path |
|
|
49
85
|
|
|
86
|
+
## How it works
|
|
87
|
+
|
|
88
|
+
The server parses each file into a sanitized HTML syntax tree (remark + GFM for
|
|
89
|
+
markdown, lowlight for code). It pushes that tree to the page over server-sent
|
|
90
|
+
events, on connect and again whenever the file changes. The page is a small
|
|
91
|
+
React app that turns the tree into elements, so an update repaints only the
|
|
92
|
+
nodes that differ. Mermaid runs in the browser from the copy installed with
|
|
93
|
+
this package.
|
|
94
|
+
|
|
95
|
+
Files are watched through their directory, so a writer that replaces a file by
|
|
96
|
+
renaming a temporary file over it is still followed. A slow poll backs up
|
|
97
|
+
`fs.watch`. Each change is rendered once however many pages show the file, and
|
|
98
|
+
one path is pushed at most once per `throttleMs`.
|
|
99
|
+
|
|
50
100
|
## Safety
|
|
51
101
|
|
|
52
102
|
- Listens on `127.0.0.1` only, and answers only requests whose `Host` names it,
|