lognal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CDGet (https://cdget.com).
+
+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

@@ -0,0 +1,99 @@
+<img src="https://raw.githubusercontent.com/jooy2/lognal/refs/heads/main/.github/resources/lognal-logo.webp" width="96" height="96" alt="lognal logo" />
+
+# lognal
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jooy2/lognal/blob/main/LICENSE) [![run-test](https://github.com/jooy2/lognal/actions/workflows/run-test.yml/badge.svg)](https://github.com/jooy2/lognal/actions/workflows/run-test.yml) ![Commit Count](https://img.shields.io/github/commit-activity/y/jooy2/lognal) [![Followers](https://img.shields.io/github/followers/jooy2?style=social)](https://github.com/jooy2) ![Stars](https://img.shields.io/github/stars/jooy2/lognal?style=social)
+
+**lognal** is a log viewer for web pages that looks and behaves like a terminal. It draws log output on a canvas instead of creating a DOM element for every line, so a fast stream of messages and a long history do not slow the page down.
+
+> **lognal is not published to npm yet.** The API described here works in this repository and may still change before the first release.
+
+## What it does
+
+- **Shows the browser console inside your page.** Hook `console.log`, `console.warn`, `console.table`, `console.group` and the rest. Arguments are captured at the moment of the call, and the original console keeps working.
+- **Reads log files.** Open a text file and read it line by line. The encoding is detected, including legacy encodings such as EUC-KR. In Chromium-based browsers, a file picked with the File System Access API can be followed as it grows.
+- **Displays values by type.** Objects, arrays, maps, sets, errors and DOM elements expand and collapse, and `console.table` draws a table.
+- **Accepts commands.** Connect a handler, and the viewer shows an input line and prints the replies.
+- **Handles Korean and other CJK text.** Wide characters stay on the grid, Korean text wraps at spaces, and Enter waits for IME composition to finish.
+
+The viewer has a toolbar (follow new logs, clear, scroll to top and bottom, line wrapping, text filter and level filter), a status bar, timestamps, light and dark themes, and a custom scrollbar. Every part can be turned off or restyled with CSS custom properties.
+
+## Quick start
+
+```bash
+npm install lognal
+```
+
+```javascript
+import { LogViewer } from 'lognal';
+import 'lognal/style.css';
+
+// The container needs a height.
+const viewer = new LogViewer(document.getElementById('logs'), {
+	timestamps: true,
+	core: { maxEntries: 20000 }
+});
+
+viewer.hookConsole();
+console.log('Hello %s', 'lognal', { id: 1, tags: ['canvas', 'logs'] });
+```
+
+With React:
+
+```jsx
+import { LogViewer } from 'lognal/react';
+import 'lognal/style.css';
+
+export const Logs = () => <LogViewer hookConsole style={{ height: 400 }} />;
+```
+
+Reading a file:
+
+```javascript
+import { readTextFile } from 'lognal';
+
+input.addEventListener('change', async () => {
+	await readTextFile(input.files[0], viewer.store);
+});
+```
+
+## Documentation
+
+The documentation is at **[lognal.cdget.com](https://lognal.cdget.com)**, in English and Korean.
+
+## Browser support
+
+lognal targets current versions of Chrome, Edge, Firefox and Safari. A few features depend on newer platform APIs:
+
+| Feature                                | Requirement                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------------ |
+| Grapheme clusters for emoji and Hangul | `Intl.Segmenter`: Chrome 87, Firefox 125, Safari 14.1. A fallback is built in. |
+| Following a growing file               | File System Access API, Chromium-based browsers only                           |
+
+## Development
+
+```bash
+npm install
+npm run dev          # playground at http://localhost:5173
+npm test             # unit tests in Node.js and browser tests in Playwright
+npm run lint
+npm run build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout and the workflow.
+
+## Contributing
+
+Anyone can contribute to the project by reporting new issues or submitting a pull request. For more information, please see [CONTRIBUTING.md](CONTRIBUTING.md). Participation is subject to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+To report a security issue, please follow the process described in [SECURITY.md](SECURITY.md).
+
+For anything that does not belong in a public issue, write to CDGet at [cdget.com/contact](https://cdget.com/contact).
+
+## Sponsor
+
+lognal is free to use and maintained in the open. If it saves you time, you can support the work at [cdget.com/donate](https://cdget.com/donate) or through the Sponsor button on GitHub.
+
+## License
+
+Please see the [LICENSE](LICENSE) file for more information about project owners, usage rights, and more. The character width tables are generated from the Unicode Character Database, whose license is included in `src/core/text/unicode-width-data.ts`.

package/dist/core/filter.d.ts

@@ -0,0 +1,29 @@
+import { type LogEntry, type LogLevel } from './types.js';
+/** Which entries a viewer shows. */
+export interface LogFilter {
+    /** Text an entry must contain. Empty text matches every entry. */
+    text?: string;
+    /** Whether `text` is a regular expression. */
+    regex?: boolean;
+    /** Whether letter case must match. */
+    caseSensitive?: boolean;
+    /** The least severe level shown. */
+    minLevel?: LogLevel;
+    /** The levels shown. When set, `minLevel` is ignored. */
+    levels?: readonly LogLevel[];
+}
+/**
+ * Returns the text of an entry as the filter sees it: its text parts, and a one-line preview of
+ * every value.
+ */
+export declare const entrySearchText: (entry: LogEntry) => string;
+/** A compiled filter. `matches` is `null` when the filter lets every entry through. */
+export interface CompiledFilter {
+    matches: ((entry: LogEntry) => boolean) | null;
+    /** Finds matches in a line of text, for highlighting. `null` when there is no text filter. */
+    pattern: RegExp | null;
+    /** Set when `text` is not a valid regular expression. */
+    error: string | null;
+}
+/** Turns a filter into a function that tests entries. */
+export declare const compileFilter: (filter: LogFilter | null | undefined) => CompiledFilter;

package/dist/core/filter.js

@@ -0,0 +1,82 @@
+import { errorTitle, previewValue } from './value/preview.js';
+import { LOG_LEVELS } from './types.js';
+/** The most characters of an entry the text filter looks at. */
+const SEARCH_TEXT_LIMIT = 20000;
+const searchTextCache = new WeakMap();
+const valueText = (node) => {
+    if (node.kind === 'error') {
+        return `${errorTitle(node)}\n${node.stack ?? ''}`;
+    }
+    return previewValue(node)
+        .map((span) => span.text)
+        .join('');
+};
+/**
+ * Returns the text of an entry as the filter sees it: its text parts, and a one-line preview of
+ * every value.
+ */
+export const entrySearchText = (entry) => {
+    const cached = searchTextCache.get(entry);
+    if (cached && cached.version === entry.version) {
+        return cached.text;
+    }
+    let text = '';
+    for (const part of entry.parts) {
+        text += part.type === 'text' ? part.text : valueText(part.value);
+        if (text.length > SEARCH_TEXT_LIMIT) {
+            text = text.slice(0, SEARCH_TEXT_LIMIT);
+            break;
+        }
+    }
+    // Compose decomposed Hangul and accented letters, so text copied from a macOS file name
+    // matches what the user types.
+    text = text.normalize('NFC');
+    searchTextCache.set(entry, { version: entry.version, text });
+    return text;
+};
+const escapeRegExp = (text) => {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};
+/** Turns a filter into a function that tests entries. */
+export const compileFilter = (filter) => {
+    if (!filter) {
+        return { matches: null, pattern: null, error: null };
+    }
+    const levels = filter.levels
+        ? new Set(filter.levels)
+        : filter.minLevel
+            ? new Set(LOG_LEVELS.slice(LOG_LEVELS.indexOf(filter.minLevel)))
+            : null;
+    let pattern = null;
+    let error = null;
+    if (filter.text) {
+        const flags = filter.caseSensitive ? 'g' : 'gi';
+        try {
+            const text = filter.text.normalize('NFC');
+            pattern = new RegExp(filter.regex ? text : escapeRegExp(text), flags);
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+    }
+    if (!levels && !pattern && !error) {
+        return { matches: null, pattern: null, error: null };
+    }
+    const matches = (entry) => {
+        if (entry.kind === 'group' && !pattern && !error) {
+            return true;
+        }
+        if (levels && entry.kind !== 'input' && entry.kind !== 'system' && !levels.has(entry.level)) {
+            return false;
+        }
+        if (error) {
+            return false;
+        }
+        if (pattern) {
+            pattern.lastIndex = 0;
+            return pattern.test(entrySearchText(entry));
+        }
+        return true;
+    };
+    return { matches, pattern, error };
+};

package/dist/core/layout/entry-lines.d.ts

@@ -0,0 +1,16 @@
+import type { LogEntry } from '../types.js';
+import type { LogicalLine } from './types.js';
+/** Cells of indentation for every level of nesting. */
+export declare const INDENT_CELLS = 2;
+/** Decides whether the value at a path is shown expanded. */
+export type ExpansionLookup = (path: string) => boolean;
+/**
+ * Returns whether a value path is expanded when the user has not toggled it: errors logged
+ * directly are open, so their stack trace is visible, and everything else is closed.
+ */
+export declare const isExpandedByDefault: (entry: LogEntry, path: string) => boolean;
+/**
+ * Builds the logical lines of an entry: one for every line of its text, followed by the rows
+ * of every expanded value in the order the values appear.
+ */
+export declare const buildEntryLines: (entry: LogEntry, isExpanded: ExpansionLookup) => LogicalLine[];

package/dist/core/layout/entry-lines.js

@@ -0,0 +1,120 @@
+import { errorTitle, formatKey, isExpandable, previewValue } from '../value/preview.js';
+/** Cells of indentation for every level of nesting. */
+export const INDENT_CELLS = 2;
+/**
+ * Returns whether a value path is expanded when the user has not toggled it: errors logged
+ * directly are open, so their stack trace is visible, and everything else is closed.
+ */
+export const isExpandedByDefault = (entry, path) => {
+    if (path.includes('.')) {
+        return false;
+    }
+    const part = entry.parts[Number(path)];
+    return part?.type === 'value' && part.value.kind === 'error';
+};
+const errorSpans = (node) => {
+    return [{ text: errorTitle(node), token: 'error' }];
+};
+const expanderSpan = (path, expanded) => {
+    return { icon: 'expander', expanded, action: { type: 'toggle-value', path } };
+};
+const childLines = (node, path, indent, isExpanded, lines) => {
+    // Rows without an expander start two cells in, so their text lines up with the text of
+    // the rows that have one.
+    const textIndent = indent + INDENT_CELLS;
+    if (node.kind === 'error' && node.stack) {
+        for (const stackLine of node.stack.split('\n')) {
+            lines.push({ indent: textIndent, spans: [{ text: stackLine.trim(), token: 'muted' }] });
+        }
+    }
+    node.children?.forEach((child, index) => {
+        childLine(node, child, `${path}.${index}`, indent, isExpanded, lines);
+    });
+    if ((node.omitted ?? 0) > 0) {
+        lines.push({ indent: textIndent, spans: [{ text: `… ${node.omitted} more`, token: 'muted' }] });
+    }
+    if (node.kind === 'element' && node.value) {
+        lines.push({ indent, spans: [{ text: `</${node.value}>`, token: 'tag' }] });
+    }
+};
+const childLine = (parent, child, path, indent, isExpanded, lines) => {
+    const expandable = isExpandable(child.value);
+    const expanded = expandable && isExpanded(path);
+    const spans = [];
+    if (expandable) {
+        spans.push(expanderSpan(path, expanded));
+    }
+    if (parent.kind === 'map' && child.keyValue) {
+        spans.push(...previewValue(child.keyValue, true), { text: ' => ', token: 'default' });
+    }
+    else if (child.key !== undefined && parent.kind !== 'set' && parent.kind !== 'element') {
+        spans.push(formatKey(child), { text: ': ', token: 'default' });
+    }
+    const action = { type: 'toggle-value', path };
+    const valueSpans = child.value.kind === 'error' ? errorSpans(child.value) : previewValue(child.value);
+    spans.push(...valueSpans.map((span) => (expandable ? { ...span, action } : span)));
+    lines.push({ indent: expandable ? indent : indent + INDENT_CELLS, spans });
+    if (expanded) {
+        childLines(child.value, path, indent + INDENT_CELLS, isExpanded, lines);
+    }
+};
+/**
+ * Builds the logical lines of an entry: one for every line of its text, followed by the rows
+ * of every expanded value in the order the values appear.
+ */
+export const buildEntryLines = (entry, isExpanded) => {
+    const baseIndent = entry.groups.length * INDENT_CELLS;
+    const lines = [];
+    let current = [];
+    let currentWraps = true;
+    const expandedParts = [];
+    if (entry.kind === 'group') {
+        current.push({
+            icon: 'expander',
+            expanded: !entry.collapsed,
+            action: { type: 'toggle-group' }
+        });
+    }
+    entry.parts.forEach((part, index) => {
+        if (part.type === 'text') {
+            const pieces = part.text.split('\n');
+            pieces.forEach((piece, pieceIndex) => {
+                if (pieceIndex > 0) {
+                    lines.push({ indent: baseIndent, spans: current, wrap: currentWraps });
+                    current = [];
+                    currentWraps = true;
+                }
+                if (part.wrap === false) {
+                    currentWraps = false;
+                }
+                if (piece) {
+                    current.push({
+                        text: piece,
+                        token: part.token,
+                        style: part.style,
+                        ...(entry.kind === 'group' ? { action: { type: 'toggle-group' } } : {})
+                    });
+                }
+            });
+            return;
+        }
+        const node = part.value;
+        const path = String(index);
+        if (!isExpandable(node)) {
+            current.push(...previewValue(node));
+            return;
+        }
+        const expanded = isExpanded(path);
+        const action = { type: 'toggle-value', path };
+        const title = node.kind === 'error' ? errorSpans(node) : previewValue(node);
+        current.push(expanderSpan(path, expanded), ...title.map((span) => ({ ...span, action })));
+        if (expanded) {
+            expandedParts.push({ node, path });
+        }
+    });
+    lines.push({ indent: baseIndent, spans: current, wrap: currentWraps });
+    for (const { node, path } of expandedParts) {
+        childLines(node, path, baseIndent + INDENT_CELLS, isExpanded, lines);
+    }
+    return lines;
+};

package/dist/core/layout/layout.d.ts

@@ -0,0 +1,152 @@
+import { type CompiledFilter, type LogFilter } from '../filter.js';
+import type { LogStore } from '../store.js';
+import { type ShapeOptions } from '../text/shape.js';
+import type { LogEntry } from '../types.js';
+import type { LineAction, TextPosition, VisualRow, WrapMode } from './types.js';
+export interface LayoutOptions extends ShapeOptions {
+    /** How lines longer than the viewer are handled. */
+    wrap: WrapMode;
+}
+export declare const DEFAULT_LAYOUT_OPTIONS: LayoutOptions;
+/**
+ * Turns the entries of a store into rows for a viewer of a given width.
+ *
+ * The layout decides which entries are visible (the filter and collapsed groups), how each
+ * entry breaks into lines and rows, and which values are expanded. It works from the store's
+ * change notifications, and does the pending work when `sync` is called, so any number of
+ * messages between two frames costs one update.
+ */
+export declare class LogLayout {
+    private readonly store;
+    private options;
+    private optionsVersion;
+    private layoutVersion;
+    private columns;
+    private filter;
+    private visible;
+    private visibleStart;
+    private readonly rowIndex;
+    private readonly layouts;
+    private readonly rowCounts;
+    private readonly expansions;
+    /** 1 where the row count of the visible entry at the same position is only an estimate. */
+    private stale;
+    private staleCount;
+    private positions;
+    private lastSyncedId;
+    private needsRebuild;
+    private dirty;
+    private widest;
+    private readonly unsubscribe;
+    constructor(store: LogStore, options?: Partial<LayoutOptions>);
+    /** The number of rows of all visible entries. Call `sync` first. */
+    get rowCount(): number;
+    /** The number of visible entries. Call `sync` first. */
+    get visibleCount(): number;
+    /** The widest row seen, in cells, including indentation. */
+    get maxCells(): number;
+    /** The number of visible entries whose row count is an estimate. See `measurePending`. */
+    get pendingCount(): number;
+    /**
+     * Increases whenever the first row of an entry that was already visible may have moved: after
+     * a rebuild, when entries are dropped from the front, and when a row count changes. Appending
+     * entries at the end does not change it. A viewer compares it between frames to keep the same
+     * entry in view.
+     */
+    get positionsVersion(): number;
+    /** Whether the store changed since the last `sync`. */
+    get isDirty(): boolean;
+    getOptions(): Readonly<LayoutOptions>;
+    setOptions(options: Partial<LayoutOptions>): void;
+    /** Sets the number of columns rows wrap into. */
+    setColumns(columns: number): void;
+    /** Sets which entries are visible. Returns the compiled filter, which reports a bad pattern. */
+    setFilter(filter: LogFilter | null): CompiledFilter;
+    /** The compiled filter in use. */
+    getFilter(): CompiledFilter;
+    /**
+     * Applies pending store changes. Returns whether anything changed.
+     *
+     * `budget` limits how many entries are laid out exactly. Past it, an entry gets an estimated
+     * row count, based on its previous layout when it had one, and is left for `measureAround`
+     * and `measurePending`. The default lays out every entry exactly.
+     */
+    sync(budget?: number): boolean;
+    /**
+     * Lays out exactly the entries around one entry: `rowsBefore` rows of the entries before it,
+     * and `rowsAfter` rows starting with it. Pass `null` to start from the last visible entry.
+     * Call it for the part of the log on screen before reading its rows. Returns whether a row
+     * count changed.
+     */
+    measureAround(entryId: number | null, rowsBefore: number, rowsAfter: number): boolean;
+    /**
+     * Lays out exactly up to `budget` entries whose row count is still an estimate, nearest to an
+     * entry first, or to the end of the log when `entryId` is `null`. Call it in small pieces of
+     * work until `pendingCount` is 0. Returns whether a row count changed.
+     */
+    measurePending(budget: number, entryId?: number | null): boolean;
+    /** Returns rows starting at a row index. Call `sync` first. */
+    getRows(start: number, count: number): VisualRow[];
+    /** Returns the entry that holds a row and the row's index within that entry. */
+    locateRow(row: number): {
+        entry: LogEntry;
+        entryRow: number;
+    } | null;
+    /** Returns the number of rows of a visible entry, or 0 when it is not visible. */
+    rowsOf(entryId: number): number;
+    /** Returns the entry at a visible position, where 0 is the oldest visible entry. */
+    entryAt(index: number): LogEntry | undefined;
+    /** Returns the visible position of an entry, or -1 when it is not visible. */
+    indexOf(entryId: number): number;
+    /** Returns the first row of an entry, or -1 when it is not visible. */
+    rowOfEntry(entryId: number): number;
+    /** Returns whether the value at a path of an entry is expanded. */
+    isExpanded(entry: LogEntry, path: string): boolean;
+    /** Runs the action of a clicked span. */
+    runAction(entryId: number, action: LineAction): void;
+    /** Expands or collapses the value at a path of an entry. */
+    setExpanded(entry: LogEntry, path: string, expanded: boolean): void;
+    /**
+     * Returns the text position under a row and a column of the content area. The position
+     * snaps to the nearest boundary between clusters.
+     */
+    positionAt(row: number, column: number): TextPosition | null;
+    /**
+     * Returns the start and end of the word at a position: a run of letters, digits, marks and
+     * underscores. On any other character, the range covers that character alone.
+     */
+    wordAt(position: TextPosition): [TextPosition, TextPosition] | null;
+    /** Returns the text between two positions, one line of the output per logical line. */
+    getText(from: TextPosition, to: TextPosition): string;
+    /** Returns the whole text of the visible entries. */
+    getAllText(): string;
+    /** Stops listening to the store. */
+    dispose(): void;
+    private onStoreChange;
+    private invalidateRows;
+    private rebuild;
+    /** Adds a visible entry with its exact row count, or an estimate once the budget is spent. */
+    private pushVisible;
+    /**
+     * Guesses the row count of an entry that was not laid out at the current width: its previous
+     * row count scaled by the change in width, and never fewer rows than it has lines.
+     */
+    private estimateRows;
+    /** Lays out the visible entry at an index exactly, if it is not already. Returns its rows. */
+    private measureIndex;
+    private isVisible;
+    private stateKeyOf;
+    private countRows;
+    /**
+     * Counts the rows of the most common entry, one line of plain ASCII text, without building and
+     * caching its layout. Returns `null` for any other entry.
+     */
+    private countPlainRows;
+    private layoutOf;
+    private buildRuns;
+    private textInCells;
+    private firstIndexFrom;
+    private forget;
+    private compactVisible;
+    private pruneCaches;
+}