@zenera/view 0.0.0-stage → 1.1.27

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { inside, isHidden, locate, type Located } from './paths.ts';
+export { drawn, languageOf, markdown, MAX_BYTES, renderPath, type RenderOptions, } from './render.ts';
+export { openBrowser, serveView, stablePort, type ViewOptions, type ViewServer } from './server.ts';
+export type { Heading, View, ViewKind } from './types.ts';
+export { stampOf, Watcher, type WatchOptions } from './watch.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export { inside, isHidden, locate } from "./paths.js";
+export { drawn, languageOf, markdown, MAX_BYTES, renderPath, } from "./render.js";
+export { openBrowser, serveView, stablePort } from "./server.js";
+export { stampOf, Watcher } from "./watch.js";
+//# sourceMappingURL=index.js.map

package/dist/paths.d.ts

@@ -0,0 +1,9 @@
+export interface Located {
+    abs: string;
+    /** the canonical URL path, `/` for the root */
+    path: string;
+}
+export declare function isHidden(name: string, hidden: boolean): boolean;
+export declare function locate(root: string, urlPath: string, hidden?: boolean): Located | undefined;
+export declare function inside(root: string, abs: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.js

@@ -0,0 +1,55 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+// ---------------------------------------------------------------------------
+// From a URL path to a file under the root, or nothing
+//
+// The root is the whole of what the server will read. A path is decoded once,
+// split, and refused on `..`, a NUL or a backslash before it is joined; then the
+// result is realpath'd - the nearest existing ancestor, for a file not written
+// yet - so a symlink inside the root cannot lead out of it.
+// ---------------------------------------------------------------------------
+/** Secrets and repository internals: never served, even with hidden files on. */
+const NEVER = /^\.(env|git|npmrc|netrc)(\.|$)/i;
+export function isHidden(name, hidden) {
+    return name.startsWith('.') && (!hidden || NEVER.test(name));
+}
+export function locate(root, urlPath, hidden = false) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(urlPath);
+    }
+    catch {
+        return undefined;
+    }
+    if (decoded.includes('\0') || decoded.includes('\\')) {
+        return undefined;
+    }
+    const parts = decoded.split('/').filter((p) => p !== '' && p !== '.');
+    if (parts.some((p) => p === '..' || isHidden(p, hidden))) {
+        return undefined;
+    }
+    const abs = join(root, ...parts);
+    if (!inside(root, real(abs))) {
+        return undefined;
+    }
+    return { abs, path: `/${parts.join('/')}` };
+}
+/** The real path, resolving the nearest ancestor that exists. */
+function real(abs) {
+    let at = abs;
+    const rest = [];
+    while (!existsSync(at)) {
+        const up = dirname(at);
+        if (up === at) {
+            return abs;
+        }
+        rest.unshift(basename(at));
+        at = up;
+    }
+    return join(realpathSync(at), ...rest);
+}
+export function inside(root, abs) {
+    const rel = relative(root, abs);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+//# sourceMappingURL=paths.js.map

package/dist/render.d.ts

@@ -0,0 +1,15 @@
+import type { Root } from 'hast';
+import type { View } from './types.ts';
+export declare const MAX_BYTES: number;
+/** Documents the browser shows better itself; the server hands them over raw. */
+export declare const NATIVE: Set<string>;
+export interface RenderOptions {
+    maxBytes?: number;
+    hidden?: boolean;
+}
+export declare function languageOf(file: string): string | undefined;
+/** Whether `path` is something the page draws, rather than a file handed over as it is. */
+export declare function drawn(file: string): boolean;
+export declare function renderPath(abs: string, path: string, options?: RenderOptions): View;
+export declare function markdown(text: string): Root;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.js

@@ -0,0 +1,372 @@
+import { common, createLowlight } from 'lowlight';
+import { closeSync, openSync, readdirSync, readSync, statSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import rehypeSanitize from 'rehype-sanitize';
+import rehypeSlug from 'rehype-slug';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+import { isHidden } from "./paths.js";
+// ---------------------------------------------------------------------------
+// From a file to a tree the page can draw
+//
+// Everything becomes hast: markdown through remark and a sanitizer, code
+// through lowlight, a directory as a table. The browser never parses anything
+// and never sees raw HTML - it turns elements into React elements, so a file
+// that changed by one number repaints one text node.
+// ---------------------------------------------------------------------------
+export const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_ENTRIES = 5000;
+const SNIFF_BYTES = 8192;
+const lowlight = createLowlight(common);
+const LANGUAGE = {
+    '.json': 'json',
+    '.jsonl': 'json',
+    '.ndjson': 'json',
+    '.py': 'python',
+    '.ts': 'typescript',
+    '.tsx': 'typescript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.yaml': 'yaml',
+    '.yml': 'yaml',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.zsh': 'bash',
+    '.patch': 'diff',
+    '.diff': 'diff',
+    '.toml': 'ini',
+    '.ini': 'ini',
+    '.css': 'css',
+    '.scss': 'scss',
+    '.xml': 'xml',
+    '.sql': 'sql',
+    '.go': 'go',
+    '.rs': 'rust',
+    '.java': 'java',
+    '.kt': 'kotlin',
+    '.c': 'c',
+    '.h': 'c',
+    '.cpp': 'cpp',
+    '.cs': 'csharp',
+    '.rb': 'ruby',
+    '.php': 'php',
+    '.lua': 'lua',
+    '.swift': 'swift',
+    '.graphql': 'graphql',
+};
+const NAMED = { makefile: 'makefile', dockerfile: 'bash' };
+const MARKDOWN = new Set(['.md', '.markdown']);
+const MERMAID = new Set(['.mmd', '.mermaid']);
+const IMAGE = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.bmp', '.ico']);
+/** Documents the browser shows better itself; the server hands them over raw. */
+export const NATIVE = new Set([...IMAGE, '.html', '.htm', '.svg', '.pdf']);
+export function languageOf(file) {
+    return LANGUAGE[extname(file).toLowerCase()] ?? NAMED[basename(file).toLowerCase()];
+}
+/** Whether `path` is something the page draws, rather than a file handed over as it is. */
+export function drawn(file) {
+    return !NATIVE.has(extname(file).toLowerCase());
+}
+export function renderPath(abs, path, options = {}) {
+    const name = path === '/' ? '/' : basename(path);
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch {
+        return {
+            path,
+            kind: 'missing',
+            title: name,
+            toc: [],
+            hast: root([
+                el('p', { className: ['note'] }, [
+                    txt('Not there yet. This page fills in when it is written.'),
+                ]),
+            ]),
+        };
+    }
+    if (stat.isDirectory()) {
+        return {
+            path,
+            kind: 'directory',
+            title: name,
+            toc: [],
+            hast: listing(abs, path, options),
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    const max = options.maxBytes ?? MAX_BYTES;
+    const { bytes, text } = readHead(abs, max);
+    const base = {
+        path,
+        title: name,
+        bytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+        ...(stat.size > max ? { truncated: { shown: max, bytes: stat.size } } : {}),
+    };
+    const ext = extname(abs).toLowerCase();
+    if (NATIVE.has(ext) || (!MARKDOWN.has(ext) && binary(bytes))) {
+        const href = `${encodeURIComponent(basename(abs))}?raw`;
+        const shown = IMAGE.has(ext)
+            ? el('img', { src: href, alt: name })
+            : el('a', { href, target: '_blank' }, [txt(`open ${name}`)]);
+        return { ...base, kind: 'binary', toc: [], hast: root([el('p', {}, [shown])]) };
+    }
+    if (MARKDOWN.has(ext)) {
+        const hast = markdown(text);
+        const toc = headings(hast);
+        return {
+            ...base,
+            kind: 'markdown',
+            title: toc.find((h) => h.depth === 1)?.text ?? name,
+            toc,
+            hast,
+        };
+    }
+    if (MERMAID.has(ext)) {
+        return {
+            ...base,
+            kind: 'mermaid',
+            toc: [],
+            hast: root([codeBlock(text, 'mermaid', false)]),
+        };
+    }
+    const language = languageOf(abs);
+    return {
+        ...base,
+        kind: language ? 'code' : 'text',
+        ...(language ? { language } : {}),
+        toc: [],
+        hast: root([codeBlock(text, language ?? 'plaintext', true)]),
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown
+// ---------------------------------------------------------------------------
+/** Raw HTML is dropped, except `<br>`: the one way a markdown table cell holds several lines. */
+const lineBreak = (_state, node) => /^<br\s*\/?>$/i.test(node.value.trim())
+    ? { type: 'element', tagName: 'br', properties: {}, children: [] }
+    : undefined;
+/** Sanitize before the slugs, so heading ids keep GitHub's form and links to them land. */
+const pipeline = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype, { handlers: { html: lineBreak } })
+    .use(rehypeSanitize)
+    .use(rehypeSlug)
+    .use(() => highlightBlocks);
+export function markdown(text) {
+    const tree = pipeline.runSync(pipeline.parse(text));
+    tidy(tree);
+    walk(tree, lineCell);
+    return tree;
+}
+/**
+ * A table cell of `<br>`-separated lines - a trailing `<br>` alone counts - is a list:
+ * one row per line, cut at the column's width by the stylesheet, whole in its tooltip.
+ */
+function lineCell(cell) {
+    if ((cell.tagName !== 'td' && cell.tagName !== 'th') ||
+        !cell.children.some((c) => c.type === 'element' && c.tagName === 'br')) {
+        return;
+    }
+    const lines = [[]];
+    for (const c of cell.children) {
+        if (c.type === 'element' && c.tagName === 'br') {
+            lines.push([]);
+        }
+        else {
+            lines.at(-1).push(c);
+        }
+    }
+    cell.properties.className = [...classes(cell), 'lines'];
+    cell.children = lines
+        .filter((l) => l.some((c) => c.type !== 'text' || c.value.trim() !== ''))
+        .map((children) => {
+        const line = {
+            type: 'element',
+            tagName: 'div',
+            properties: { className: ['line'] },
+            children,
+        };
+        line.properties.title = textOf(line).trim();
+        return line;
+    });
+}
+const TABLE_PARTS = new Set(['table', 'thead', 'tbody', 'tfoot', 'tr']);
+/** Source positions are most of the bytes sent and the page needs none of them. */
+function tidy(node) {
+    delete node.position;
+    if (node.type === 'element' && TABLE_PARTS.has(node.tagName)) {
+        node.children = node.children.filter((c) => c.type !== 'text' || c.value.trim() !== '');
+    }
+    for (const child of node.children) {
+        if (child.type === 'element') {
+            tidy(child);
+        }
+        else {
+            delete child.position;
+        }
+    }
+}
+function highlightBlocks(tree) {
+    walk(tree, (node) => {
+        if (node.tagName !== 'pre') {
+            return;
+        }
+        const code = node.children.find((c) => c.type === 'element' && c.tagName === 'code');
+        const lang = classes(code)
+            .find((c) => c.startsWith('language-'))
+            ?.slice('language-'.length);
+        if (!code || !lang || lang === 'mermaid' || !lowlight.registered(lang)) {
+            return;
+        }
+        code.children = lowlight.highlight(lang, textOf(code)).children;
+        code.properties.className = [...classes(code), 'hljs'];
+    });
+}
+function headings(tree) {
+    const out = [];
+    walk(tree, (node) => {
+        const depth = /^h([1-3])$/.exec(node.tagName)?.[1];
+        const id = node.properties.id;
+        if (depth && typeof id === 'string') {
+            out.push({ depth: Number(depth), id, text: textOf(node).trim() });
+        }
+    });
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Code, text, directories
+// ---------------------------------------------------------------------------
+function codeBlock(text, language, highlight) {
+    const children = highlight && language !== 'plaintext' && lowlight.registered(language)
+        ? lowlight.highlight(language, text).children
+        : [txt(text)];
+    return el('pre', {}, [el('code', { className: ['hljs', `language-${language}`] }, children)]);
+}
+function listing(abs, path, options) {
+    const here = path === '/' ? '' : path;
+    const rows = [];
+    if (path !== '/') {
+        rows.push(row(el('a', { href: `${here.slice(0, here.lastIndexOf('/')) || '/'}` }, [txt('..')]), '', ''));
+    }
+    let names = [];
+    try {
+        names = readdirSync(abs, { withFileTypes: true })
+            .filter((d) => !isHidden(d.name, options.hidden ?? false))
+            .slice(0, MAX_ENTRIES)
+            .map((d) => {
+            try {
+                const s = statSync(join(abs, d.name));
+                return { name: d.name, dir: s.isDirectory(), size: s.size, mtimeMs: s.mtimeMs };
+            }
+            catch {
+                return { name: d.name, dir: d.isDirectory(), size: 0, mtimeMs: 0 };
+            }
+        });
+    }
+    catch {
+        // Unreadable: an empty listing says as much.
+    }
+    names.sort((a, b) => Number(b.dir) - Number(a.dir) || a.name.localeCompare(b.name));
+    for (const n of names) {
+        const href = `${here}/${encodeURIComponent(n.name)}${n.dir ? '/' : ''}`;
+        rows.push(row(el('a', { href }, [txt(n.dir ? `${n.name}/` : n.name)]), n.dir ? '' : size(n.size), stamp(n.mtimeMs)));
+    }
+    return root([
+        el('table', { className: ['listing'] }, [
+            el('thead', {}, [
+                el('tr', {}, ['name', 'size', 'modified'].map((h) => el('th', {}, [txt(h)]))),
+            ]),
+            el('tbody', {}, rows),
+        ]),
+    ]);
+}
+const row = (name, bytes, at) => el('tr', {}, [
+    el('td', {}, [name]),
+    el('td', { className: ['num'] }, [txt(bytes)]),
+    el('td', {}, [txt(at)]),
+]);
+function size(n) {
+    if (n < 1000) {
+        return `${n} B`;
+    }
+    const units = ['kB', 'MB', 'GB'];
+    let v = n / 1000;
+    let i = 0;
+    while (v >= 1000 && i < units.length - 1) {
+        v /= 1000;
+        i++;
+    }
+    return `${v.toFixed(v < 10 ? 1 : 0)} ${units[i]}`;
+}
+function stamp(ms) {
+    if (!ms) {
+        return '';
+    }
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+function readHead(abs, max) {
+    const fd = openSync(abs, 'r');
+    try {
+        const buf = Buffer.alloc(max);
+        let n = 0;
+        for (let got = -1; got !== 0 && n < max; n += got) {
+            got = readSync(fd, buf, n, max - n, null);
+        }
+        const bytes = buf.subarray(0, n);
+        return { bytes, text: new TextDecoder().decode(bytes) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function binary(bytes) {
+    return bytes.subarray(0, SNIFF_BYTES).includes(0);
+}
+// ---------------------------------------------------------------------------
+// hast helpers
+// ---------------------------------------------------------------------------
+const root = (children) => ({ type: 'root', children });
+const el = (tagName, properties = {}, children = []) => ({
+    type: 'element',
+    tagName,
+    properties,
+    children,
+});
+const txt = (value) => ({ type: 'text', value });
+function classes(node) {
+    const c = node?.properties.className;
+    return Array.isArray(c) ? c.map(String) : typeof c === 'string' ? c.split(' ') : [];
+}
+function walk(node, visit) {
+    for (const child of node.children) {
+        if (child.type === 'element') {
+            visit(child);
+            walk(child, visit);
+        }
+    }
+}
+function textOf(node) {
+    let out = '';
+    for (const child of node.children) {
+        if (child.type === 'text') {
+            out += child.value;
+        }
+        else if (child.type === 'element') {
+            out += textOf(child);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=render.js.map

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+export interface ViewOptions {
+    /** the directory served; nothing outside it is read */
+    root: string;
+    /** default: a port derived from the root, or any free one if that is taken */
+    port?: number;
+    /** the page the returned `url` opens, as a URL path */
+    start?: string;
+    /** serve dotfiles too; `.env`, `.git` and the like never are */
+    hidden?: boolean;
+    /** most of one file rendered, in bytes */
+    maxBytes?: number;
+    /** most pages open at once */
+    maxClients?: number;
+    pollMs?: number;
+    /** least time between two pushes of one path, in ms; default 1000 */
+    throttleMs?: number;
+}
+export interface ViewServer {
+    readonly url: string;
+    readonly origin: string;
+    readonly port: number;
+    readonly root: string;
+    close(): Promise<void>;
+}
+/** The same root asks for the same port, so an open tab reconnects after a restart. */
+export declare function stablePort(root: string): number;
+/** The platform opener, without a shell, so the URL stays one argument. */
+export declare function openBrowser(url: string): void;
+export declare function serveView(options: ViewOptions): Promise<ViewServer>;
+//# sourceMappingURL=server.d.ts.map