@zenera/view 0.0.0-stage → 1.1.27

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ryabov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-view-dark.svg">
+  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-view-light.svg" alt="ZENERA VIEW" width="747">
+</picture>
 
-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.
+[![npm](https://img.shields.io/npm/v/@zenera/view.svg)](https://www.npmjs.com/package/@zenera/view)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+
+</div>
+
+# @zenera/view
+
+**A live local viewer for a folder. Markdown with tables and Mermaid diagrams,
+highlighted code, directory listings - redrawn in place as the files change.**
+
+> Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). It ships with
+> [`zen`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md)
+> as the `view` **subcommand**, and works just as well as a library on its own.
+
+## Why
+
+Agents write reports, plans, traces and diagrams to disk, and keep rewriting
+them while they work. `@zenera/view` turns that folder into a page you can leave
+open: every change shows up within a second, with no reload, no lost scroll
+position, and no flicker of diagrams that did not change.
+
+- **Markdown as GitHub draws it** - GFM tables, task lists, heading anchors and
+  [Mermaid](https://mermaid.js.org) diagrams.
+- **Highlighted code** - `.json`, `.jsonl`, `.py`, `.ts`, `.yaml`, `.patch` and more.
+- **Directories as listings**, so the whole tree is navigable from one page.
+- **Everything else as is** - images, HTML and PDF are handed to the browser.
+- **Live, minimal updates** - only the nodes that changed are repainted.
+- **Local and offline** - loopback only, nothing fetched from the network.
+
+## Install
+
+Node.js 24+, ESM only. It comes with the CLI:
+
+```sh
+npm i -g @zenera/cli
+```
+
+or on its own, as a library:
+
+```sh
+npm i @zenera/view
+```
+
+## Use
+
+### From the command line
+
+```sh
+zen view                              # this folder
+zen view finetune/STATUS.md --open    # one file, opened in the browser
+```
+
+`zen view` serves until Ctrl-C and prints its address. `--port`, `--throttle`
+and `--hidden` map to the options below; `zen view --help` has the details.
+
+### From code
+
+```ts
+import { serveView } from '@zenera/view';
+
+const server = await serveView({ root: './reports', start: '/STATUS.md' });
+console.log(server.url); // http://127.0.0.1:<port>/STATUS.md
+// ...
+await server.close();
+```
+
+### Options
+
+| option       | default                        | meaning                                     |
+| ------------ | ------------------------------ | ------------------------------------------- |
+| `root`       | -                              | the directory served; nothing outside it    |
+| `port`       | derived from `root`, else free | a page left open reconnects after a restart |
+| `start`      | `/`                            | the page `url` opens                        |
+| `hidden`     | `false`                        | serve dotfiles; `.env`, `.git` never are    |
+| `maxBytes`   | 2 MB                           | the most of one file rendered               |
+| `maxClients` | 64                             | pages open at once                          |
+| `throttleMs` | 1000                           | least time between two pushes of one path   |
+
+## How it works
+
+The server parses each file into a sanitized HTML syntax tree (remark + GFM for
+markdown, lowlight for code). It pushes that tree to the page over server-sent
+events, on connect and again whenever the file changes. The page is a small
+React app that turns the tree into elements, so an update repaints only the
+nodes that differ. Mermaid runs in the browser from the copy installed with
+this package.
+
+Files are watched through their directory, so a writer that replaces a file by
+renaming a temporary file over it is still followed. A slow poll backs up
+`fs.watch`. Each change is rendered once however many pages show the file, and
+one path is pushed at most once per `throttleMs`.
+
+## Safety
+
+- Listens on `127.0.0.1` only, and answers only requests whose `Host` names it,
+  so a web page cannot reach it through a DNS name pointed at loopback.
+- Every path is resolved to a real path under the root; `..`, symlinks out of
+  the root, dotfiles and secrets are refused.
+- Markdown is sanitized and raw HTML in it is dropped; the page runs under a
+  strict Content-Security-Policy. Files served as they are (HTML, SVG, …) carry
+  a `sandbox` CSP, so they run - if at all - in an origin of their own.
+
+## License
+
+MIT

package/dist/client/app.css

@@ -0,0 +1 @@
+:root{color-scheme:light dark;--fg: #24292f;--muted: #57606a;--bg: #ffffff;--panel: #f6f8fa;--line: #d0d7de;--link: #0969da;--hover: #eaeef2;--on: #ddf4ff;--ok: #1a7f37;--warn: #9a6700;--err: #cf222e;--hl-keyword: #cf222e;--hl-string: #0a3069;--hl-number: #0550ae;--hl-attr: #0550ae;--hl-title: #8250df;--hl-comment: #6e7781;--hl-meta: #953800;--hl-add: #116329;--hl-add-bg: #dafbe1;--hl-del: #82071e;--hl-del-bg: #ffebe9}@media(prefers-color-scheme:dark){:root{--fg: #e6edf3;--muted: #8d96a0;--bg: #0d1117;--panel: #161b22;--line: #30363d;--link: #4493f8;--hover: #1f242c;--on: #12233a;--ok: #3fb950;--warn: #d29922;--err: #f85149;--hl-keyword: #ff7b72;--hl-string: #a5d6ff;--hl-number: #79c0ff;--hl-attr: #79c0ff;--hl-title: #d2a8ff;--hl-comment: #8b949e;--hl-meta: #ffa657;--hl-add: #aff5b4;--hl-add-bg: #033a16;--hl-del: #ffdcd7;--hl-del-bg: #67060c}}body{font:14px/1.5 system-ui,sans-serif;margin:0;color:var(--fg);background:var(--bg)}a{color:var(--link)}#toc{position:fixed;top:0;left:0;bottom:0;width:220px;overflow:auto;padding:1em 6px;box-sizing:border-box;border-right:1px solid var(--line);background:var(--panel);font-size:13px}#toc a{display:block;padding:2px 8px;border-radius:4px;color:var(--fg);text-decoration:none;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}#toc a.top{font-weight:600;margin-bottom:6px}#toc a.sub{padding-left:22px;color:var(--muted)}#toc a:hover{background:var(--hover)}#toc a.on{background:var(--on);color:var(--link);font-weight:600}#page.with-toc{margin-left:220px}header{position:sticky;top:0;z-index:2;display:flex;gap:1em;justify-content:space-between;align-items:baseline;padding:6px 2em;background:var(--bg);border-bottom:1px solid var(--line);font-size:13px}header .crumbs a{text-decoration:none}header .aside{display:flex;gap:1em;color:var(--muted);white-space:nowrap}.link:before{content:"\25cf";margin-right:4px}.link.live:before{color:var(--ok)}.link.connecting:before{color:var(--warn)}.link.lost:before{color:var(--err)}main{padding:1em 2em;max-width:1600px}h1,h2,h3,h4{scroll-margin-top:44px}.note{color:var(--muted)}@media(max-width:800px){#toc{display:none}#page.with-toc{margin-left:0}}.table-wrap{overflow:auto;max-height:75vh;margin:1em 0;border:1px solid var(--line);width:fit-content;max-width:100%}table{border-collapse:collapse}.table-wrap table{margin:0}th,td{border:1px solid var(--line);padding:4px 8px;vertical-align:top}.table-wrap tr:first-child>*{border-top:none}.table-wrap tr>:first-child{border-left:none}.table-wrap tr>:last-child{border-right:none}th{background:var(--panel);position:sticky;top:0;z-index:1}td.num{text-align:right;white-space:nowrap}table.listing td{white-space:nowrap}.table-wrap:has(td.lines),.table-wrap:has(td.lines) table{width:100%}td.lines{width:40%}td.lines>.line{contain:inline-size;min-width:24ch;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}code{font:12.5px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;background:var(--panel);padding:0 4px;border-radius:4px}pre{background:var(--panel);padding:8px 12px;overflow:auto;border-radius:6px}pre code{padding:0;background:none}main.code pre,main.text pre{margin:0}.mermaid{margin:1em 0;overflow:auto}.mermaid-svg svg{max-width:100%;height:auto}.mermaid-error{color:var(--err);font-size:12px;white-space:pre-wrap}main.mermaid .mermaid-svg svg{max-width:none}img{max-width:100%}.hljs-keyword,.hljs-selector-tag,.hljs-built_in,.hljs-literal,.hljs-type{color:var(--hl-keyword)}.hljs-string,.hljs-regexp,.hljs-symbol{color:var(--hl-string)}.hljs-number,.hljs-variable,.hljs-template-variable{color:var(--hl-number)}.hljs-attr,.hljs-attribute,.hljs-property,.hljs-selector-class,.hljs-selector-id{color:var(--hl-attr)}.hljs-title,.hljs-section,.hljs-name{color:var(--hl-title)}.hljs-comment,.hljs-quote{color:var(--hl-comment);font-style:italic}.hljs-meta,.hljs-params{color:var(--hl-meta)}.hljs-addition{color:var(--hl-add);background:var(--hl-add-bg)}.hljs-deletion{color:var(--hl-del);background:var(--hl-del-bg)}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:600}