@zenera/view 0.0.0-stage → 1.1.26

package/dist/server.js

@@ -0,0 +1,406 @@
+import { spawn } from 'node:child_process';
+import { closeSync, createReadStream, existsSync, openSync, readSync, realpathSync, statSync, } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { locate } from "./paths.js";
+import { drawn, MAX_BYTES, renderPath } from "./render.js";
+import { stampOf, Watcher } from "./watch.js";
+const HOST = '127.0.0.1';
+const PORT_BASE = 20000;
+const PORT_SPAN = 20000;
+const BEAT_MS = 25_000;
+const THROTTLE_MS = 1000;
+const CACHED = 64;
+/** The same root asks for the same port, so an open tab reconnects after a restart. */
+export function stablePort(root) {
+    let h = 0x811c9dc5;
+    for (const ch of realpathSync(resolve(root))) {
+        h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193) >>> 0;
+    }
+    return PORT_BASE + (h % PORT_SPAN);
+}
+/** The platform opener, without a shell, so the URL stays one argument. */
+export function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'explorer'
+            : 'xdg-open';
+    spawn(command, [url], { stdio: 'ignore', detached: true })
+        .on('error', () => { })
+        .unref();
+}
+export async function serveView(options) {
+    const root = realpathSync(resolve(options.root));
+    if (!statSync(root).isDirectory()) {
+        throw new Error(`not a directory: ${root}`);
+    }
+    const hidden = options.hidden ?? false;
+    const render = { maxBytes: options.maxBytes ?? MAX_BYTES, hidden };
+    const maxClients = options.maxClients ?? 64;
+    const throttleMs = options.throttleMs ?? THROTTLE_MS;
+    const watcher = new Watcher({ pollMs: options.pollMs });
+    const clients = new Set();
+    const feeds = new Map();
+    const cache = new Map();
+    let hosts = new Set();
+    const server = createServer((req, res) => {
+        try {
+            handle(req, res);
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                plain(res, 500, err instanceof Error ? err.message : String(err));
+            }
+            else {
+                res.end();
+            }
+        }
+    });
+    function handle(req, res) {
+        if (!hosts.has(req.headers.host ?? '')) {
+            return plain(res, 403, 'unknown host');
+        }
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            return plain(res, 405, 'read only');
+        }
+        const url = new URL(req.url ?? '/', 'http://view');
+        if (url.pathname.startsWith('/_view/')) {
+            return internal(req, res, url);
+        }
+        const at = locate(root, url.pathname, hidden);
+        if (!at) {
+            return plain(res, 404, 'not found');
+        }
+        const file = isFile(at.abs);
+        if (url.searchParams.has('raw') || (file && !drawn(at.abs))) {
+            return file ? sendFile(res, at.abs, rawHeaders(at.abs)) : plain(res, 404, 'not found');
+        }
+        return page(res);
+    }
+    function internal(req, res, url) {
+        const name = url.pathname.slice('/_view/'.length);
+        if (name === 'events') {
+            return events(req, res, url);
+        }
+        if (name === 'render') {
+            const at = locate(root, url.searchParams.get('path') ?? '/', hidden);
+            return at
+                ? send(res, 200, 'application/json', rendered(at.abs, at.path))
+                : plain(res, 404, 'not found');
+        }
+        if (name === 'health') {
+            return send(res, 200, 'application/json', JSON.stringify({ ok: true, root }));
+        }
+        if (name === 'app.js' || name === 'app.css') {
+            const file = join(clientDir(), name);
+            return existsSync(file)
+                ? sendFile(res, file, {
+                    'content-type': TYPES[extname(name)],
+                    'cache-control': 'no-cache',
+                })
+                : plain(res, 404, `${name} is not built: npm run build`);
+        }
+        if (name.startsWith('mermaid/')) {
+            const dir = mermaidDir();
+            const at = dir && locate(dir, name.slice('mermaid/'.length));
+            return at && isFile(at.abs)
+                ? sendFile(res, at.abs, {
+                    'content-type': TYPES[extname(at.abs)] ?? 'text/javascript',
+                    'cache-control': 'max-age=3600',
+                })
+                : plain(res, 404, 'not found');
+        }
+        return plain(res, 404, 'not found');
+    }
+    function view(abs, path) {
+        try {
+            return renderPath(abs, path, render);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                path,
+                kind: 'text',
+                title: path,
+                toc: [],
+                hast: {
+                    type: 'root',
+                    children: [
+                        {
+                            type: 'element',
+                            tagName: 'pre',
+                            properties: {},
+                            children: [{ type: 'text', value: `cannot read it: ${message}` }],
+                        },
+                    ],
+                },
+            };
+        }
+    }
+    /** The view as JSON, rendered again only when the file's stamp moved. */
+    function rendered(abs, path) {
+        const stamp = stampOf(abs);
+        const hit = cache.get(path);
+        if (hit?.stamp === stamp) {
+            return hit.json;
+        }
+        const json = JSON.stringify(view(abs, path));
+        cache.delete(path);
+        cache.set(path, { stamp, json });
+        if (cache.size > CACHED) {
+            cache.delete(cache.keys().next().value);
+        }
+        return json;
+    }
+    function refresh(feed) {
+        clearTimeout(feed.timer);
+        feed.timer = undefined;
+        feed.at = Date.now();
+        const json = rendered(feed.abs, feed.path);
+        if (json === feed.json) {
+            return;
+        }
+        feed.json = json;
+        for (const res of feed.clients) {
+            res.write(`event: view\ndata: ${json}\n\n`);
+        }
+    }
+    /** Leading and trailing: a change after a quiet spell goes out at once, a burst once per window. */
+    function changed(feed) {
+        if (feed.timer) {
+            return;
+        }
+        const wait = feed.at + throttleMs - Date.now();
+        if (wait <= 0) {
+            return refresh(feed);
+        }
+        feed.timer = setTimeout(() => refresh(feed), wait);
+        feed.timer.unref();
+    }
+    function feedOf(abs, path) {
+        let feed = feeds.get(path);
+        if (!feed) {
+            const f = { abs, path, clients: new Set(), json: '', at: 0, off: () => { } };
+            // Subscribed before the first render, so a write in between is not missed.
+            f.off = watcher.subscribe(abs, () => changed(f));
+            refresh(f);
+            feeds.set(path, f);
+            feed = f;
+        }
+        return feed;
+    }
+    function events(req, res, url) {
+        const at = locate(root, url.searchParams.get('path') ?? '/', hidden);
+        if (!at) {
+            return plain(res, 404, 'not found');
+        }
+        if (clients.size >= maxClients) {
+            return plain(res, 503, 'too many pages open');
+        }
+        res.writeHead(200, {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-cache',
+            'x-content-type-options': 'nosniff',
+        });
+        res.write('retry: 1000\n\n');
+        const feed = feedOf(at.abs, at.path);
+        res.write(`event: view\ndata: ${feed.json}\n\n`);
+        feed.clients.add(res);
+        const beat = setInterval(() => res.write(': beat\n\n'), BEAT_MS);
+        beat.unref();
+        clients.add(res);
+        req.on('close', () => {
+            clearInterval(beat);
+            clients.delete(res);
+            feed.clients.delete(res);
+            if (feed.clients.size === 0 && feeds.get(feed.path) === feed) {
+                feed.off();
+                clearTimeout(feed.timer);
+                feeds.delete(feed.path);
+            }
+        });
+    }
+    const preferred = options.port ?? stablePort(root);
+    let port;
+    try {
+        port = await listen(server, preferred);
+    }
+    catch (err) {
+        if (options.port !== undefined || err.code !== 'EADDRINUSE') {
+            throw err;
+        }
+        port = await listen(server, 0);
+    }
+    hosts = new Set([`${HOST}:${port}`, `localhost:${port}`]);
+    const origin = `http://${HOST}:${port}`;
+    return {
+        url: `${origin}${encodeURI(options.start ?? '/')}`,
+        origin,
+        port,
+        root,
+        close: async () => {
+            for (const feed of feeds.values()) {
+                clearTimeout(feed.timer);
+            }
+            feeds.clear();
+            cache.clear();
+            watcher.close();
+            for (const res of clients) {
+                res.end();
+            }
+            clients.clear();
+            server.closeAllConnections();
+            await new Promise((done) => server.close(() => done()));
+        },
+    };
+}
+function listen(server, port) {
+    return new Promise((done, fail) => {
+        server.once('error', fail);
+        server.listen(port, HOST, () => {
+            server.off('error', fail);
+            done(server.address().port);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+const TYPES = {
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.json': 'application/json; charset=utf-8',
+};
+const PAGE_CSP = [
+    "default-src 'none'",
+    "script-src 'self'",
+    // Mermaid writes a <style> into every diagram it draws.
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data:",
+    "font-src 'self' data:",
+    "connect-src 'self'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+].join('; ');
+/** A served file is untrusted: it runs, if at all, in an origin of its own. */
+function rawHeaders(abs) {
+    const ext = extname(abs).toLowerCase();
+    const type = TYPES[ext] ?? (looksBinary(abs) ? 'application/octet-stream' : 'text/plain; charset=utf-8');
+    const html = ext === '.html' || ext === '.htm';
+    return {
+        'content-type': type,
+        'content-security-policy': html ? 'sandbox allow-scripts allow-popups' : 'sandbox',
+        'cache-control': 'no-cache',
+    };
+}
+function page(res) {
+    send(res, 200, 'text/html; charset=utf-8', `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>view</title>
+<link rel="stylesheet" href="/_view/app.css">
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/_view/app.js"></script>
+</body>
+</html>
+`, { 'content-security-policy': PAGE_CSP, 'cache-control': 'no-cache' });
+}
+function send(res, status, type, body, headers = {}) {
+    res.writeHead(status, {
+        'content-type': type,
+        'content-length': Buffer.byteLength(body),
+        'x-content-type-options': 'nosniff',
+        'referrer-policy': 'no-referrer',
+        ...headers,
+    });
+    res.end(res.req.method === 'HEAD' ? undefined : body);
+}
+function plain(res, status, text) {
+    send(res, status, 'text/plain; charset=utf-8', `${text}\n`);
+}
+function sendFile(res, abs, headers) {
+    const size = statSync(abs).size;
+    res.writeHead(200, {
+        'content-length': size,
+        'x-content-type-options': 'nosniff',
+        'referrer-policy': 'no-referrer',
+        ...headers,
+    });
+    if (res.req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    createReadStream(abs)
+        .on('error', () => res.destroy())
+        .pipe(res);
+}
+function isFile(abs) {
+    try {
+        return statSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function looksBinary(abs) {
+    let fd;
+    try {
+        fd = openSync(abs, 'r');
+        const head = Buffer.alloc(8192);
+        return head.subarray(0, readSync(fd, head, 0, head.length, 0)).includes(0);
+    }
+    catch {
+        return true;
+    }
+    finally {
+        if (fd !== undefined) {
+            closeSync(fd);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Where the browser half and Mermaid come from
+// ---------------------------------------------------------------------------
+function clientDir() {
+    // dist/client beside the compiled server; ../dist/client when run from source.
+    for (const rel of ['./client/', '../dist/client/']) {
+        const dir = fileURLToPath(new URL(rel, import.meta.url));
+        if (existsSync(join(dir, 'app.js'))) {
+            return dir;
+        }
+    }
+    return fileURLToPath(new URL('./client/', import.meta.url));
+}
+let mermaidAt;
+function mermaidDir() {
+    if (mermaidAt === undefined) {
+        try {
+            mermaidAt = realpathSync(dirname(fileURLToPath(import.meta.resolve('mermaid'))));
+        }
+        catch {
+            mermaidAt = null;
+        }
+    }
+    return mermaidAt ?? undefined;
+}
+//# sourceMappingURL=server.js.map

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import type { Root } from 'hast';
+export type ViewKind = 'markdown' | 'code' | 'mermaid' | 'text' | 'directory' | 'binary' | 'missing';
+export interface Heading {
+    depth: number;
+    id: string;
+    text: string;
+}
+/** One file or directory, rendered: what the page draws, and nothing it must work out. */
+export interface View {
+    /** the URL path, `/` separated, always starting with `/` */
+    path: string;
+    kind: ViewKind;
+    title: string;
+    /** sanitized: every element and attribute in it is safe to hand to React */
+    hast: Root;
+    toc: Heading[];
+    language?: string;
+    bytes?: number;
+    mtimeMs?: number;
+    /** only the first `shown` bytes of `bytes` were rendered */
+    truncated?: {
+        shown: number;
+        bytes: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/watch.d.ts

@@ -0,0 +1,13 @@
+export interface WatchOptions {
+    debounceMs?: number;
+    pollMs?: number;
+}
+export declare function stampOf(abs: string): string;
+export declare class Watcher {
+    #private;
+    constructor(options?: WatchOptions);
+    /** Calls `notify` whenever `abs` changes, until the returned function is called. */
+    subscribe(abs: string, notify: () => void): () => void;
+    close(): void;
+}
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.js

@@ -0,0 +1,110 @@
+import { readdirSync, statSync, watch } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function stampOf(abs) {
+    try {
+        const s = statSync(abs);
+        if (!s.isDirectory()) {
+            return `${s.ino}:${s.size}:${s.mtimeMs}`;
+        }
+        return readdirSync(abs)
+            .sort()
+            .map((name) => {
+            try {
+                const e = statSync(join(abs, name));
+                return `${name}:${e.size}:${e.mtimeMs}`;
+            }
+            catch {
+                return name;
+            }
+        })
+            .join('/');
+    }
+    catch {
+        return 'missing';
+    }
+}
+export class Watcher {
+    #dirs = new Map();
+    #due = new Set();
+    #debounceMs;
+    #timer;
+    #poll;
+    constructor(options = {}) {
+        this.#debounceMs = options.debounceMs ?? 75;
+        this.#poll = setInterval(() => this.#check(this.#all()), options.pollMs ?? 2000);
+        this.#poll.unref();
+    }
+    /** Calls `notify` whenever `abs` changes, until the returned function is called. */
+    subscribe(abs, notify) {
+        const dir = isDir(abs) ? abs : dirname(abs);
+        const sub = { abs, dir, stamp: stampOf(abs), notify };
+        let d = this.#dirs.get(dir);
+        if (!d) {
+            d = { subs: new Set(), ...this.#open(dir) };
+            this.#dirs.set(dir, d);
+        }
+        d.subs.add(sub);
+        return () => {
+            const at = this.#dirs.get(dir);
+            at?.subs.delete(sub);
+            this.#due.delete(sub);
+            if (at && at.subs.size === 0) {
+                at.watcher?.close();
+                this.#dirs.delete(dir);
+            }
+        };
+    }
+    close() {
+        clearInterval(this.#poll);
+        clearTimeout(this.#timer);
+        for (const d of this.#dirs.values()) {
+            d.watcher?.close();
+        }
+        this.#dirs.clear();
+        this.#due.clear();
+    }
+    #open(dir) {
+        try {
+            const watcher = watch(dir, { persistent: false }, () => this.#schedule(dir));
+            // A directory removed under a watch errors; the poll carries on without it.
+            watcher.on('error', () => watcher.close());
+            return { watcher };
+        }
+        catch {
+            return {};
+        }
+    }
+    #schedule(dir) {
+        for (const sub of this.#dirs.get(dir)?.subs ?? []) {
+            this.#due.add(sub);
+        }
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            const due = [...this.#due];
+            this.#due.clear();
+            this.#check(due);
+        }, this.#debounceMs);
+        this.#timer.unref();
+    }
+    #all() {
+        return [...this.#dirs.values()].flatMap((d) => [...d.subs]);
+    }
+    #check(subs) {
+        for (const sub of subs) {
+            const stamp = stampOf(sub.abs);
+            if (stamp !== sub.stamp) {
+                sub.stamp = stamp;
+                sub.notify();
+            }
+        }
+    }
+}
+function isDir(abs) {
+    try {
+        return statSync(abs).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=watch.js.map

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@zenera/view",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zenera/view",
+    "version": "1.1.26",
+    "description": "A live local viewer for a folder: markdown with mermaid, highlighted code, updated in place as the files change.",
+    "keywords": [
+        "markdown",
+        "mermaid",
+        "viewer",
+        "live-reload",
+        "syntax-highlighting"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Andrey Ryabov",
+    "homepage": "https://github.com/andreyryabov/ZeneraNeo#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/andreyryabov/ZeneraNeo.git",
+        "directory": "packages/view"
+    },
+    "bugs": "https://github.com/andreyryabov/ZeneraNeo/issues",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "build": "tsc -b && node scripts/bundle.mjs",
+        "bundle": "node scripts/bundle.mjs",
+        "clean": "tsc -b --clean && rm -rf dist",
+        "prepack": "tsc -b && node scripts/bundle.mjs"
+    },
+    "devDependencies": {
+        "@types/react-dom": "^19.3.0",
+        "esbuild": "^0.28.2",
+        "hast-util-to-jsx-runtime": "^2.3.6",
+        "react": "^19.3.1",
+        "react-dom": "^19.3.1"
+    },
+    "dependencies": {
+        "@types/hast": "^3.0.5",
+        "lowlight": "^3.3.0",
+        "mermaid": "^12.2.0",
+        "rehype-sanitize": "^6.0.0",
+        "rehype-slug": "^6.0.0",
+        "remark-gfm": "^4.0.1",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "^11.1.2",
+        "unified": "^11.0.5"
+    }
+}