$ show vinta/pangu.js
pangu.js is a TypeScript text-spacing library that automatically inserts whitespace between CJK (Chinese, Japanese, Korean) characters and half-width letters, numbers, and symbols for improved readability. It ships as an npm package (ESM/CommonJS/UMD) with a Node.js API, a CLI tool, and a Chrome Manifest V3 browser extension. The core spacing engine in `src/shared/index.ts` implements the Paranoid Text Spacing algorithm with dozens of regex rules handling operators, brackets, quotes, punctuation, file paths, HTML tags, and per-line readings for slashes, pipes, and plus signs. The browser layer adds DOM-aware features: `spacingNode()` processes individual elements, `autoSpacingPage()` uses MutationObserver and requestIdleCallback for dynamic content, and boundary-spacing logic decides where to insert spaces between adjacent text runs across markup boundaries. The Chrome extension registers content scripts dynamically based on user settings (blacklist/whitelist, auto vs manual mode) and supports native `text-autospace` CSS as a visual-only layer. The architecture is modular with three build targets: a shared platform-agnostic engine, a Node.js entry with file I/O, and a browser entry with DOM traversal. The build uses Vite with multiple environments to produce self-contained ESM, UMD, and CJS bundles. The project has zero runtime dependencies, extensive test coverage (Vitest for shared/Node logic, Playwright for browser behavior), and a comprehensive set of Architecture Decision Records (ADRs) documenting every significant design choice. The Chrome extension is fully localized in Traditional Chinese and includes sound effects, a popup UI, and an options page for configuring spacing mode, site filters, and native autospacing. Key entry points: `pangu.spacingText()` for plain text, `pangu.spacingNode()` for DOM elements, `pangu.autoSpacingPage()` for live page monitoring, and the CLI (`pangu` command) for file/stdin processing. External dependencies are limited to Node.js built-in modules (`node:fs`, `node:path`) for the Node build; the browser build and shared engine have no dependencies at all. The Chrome extension uses only Chrome extension APIs (`chrome.storage`, `chrome.scripting`, `chrome.tabs`).
The LLM identified 2 files worth highlighting for reuse:
A self-contained module that decides whether and how to insert whitespace at the boundary between two adjacent text runs in the DOM. It exports pure functions `decideBoundarySpacing()` and `decideTextRunSpacing()` that take a context object with both cheap facts (e.g., does the run end with a space?) and lazy layout-dependent facts (e.g., is the boundary hidden? is the parent a grid/flex container?). The lazy facts are supplied as closures and only consulted when the cheap checks pass, avoiding unnecessary style recalculations. The module also includes `respaceCurrentTail()` for handling split slash junctions (e.g., CJK/ + CJK across a `<wbr>`). This pattern is reusable in any project that needs to insert content between adjacent text nodes while respecting layout context, and it demonstrates non-obvious skill in separating cheap vs expensive checks and memoizing spaced junctions.
The core text spacing engine implementing the Paranoid Text Spacing algorithm. It contains the `Pangu` class with `spacingText()` method that applies dozens of carefully ordered regex replacements for CJK-ANS spacing, operator handling, bracket spacing, quote pairing, file path detection, HTML tag protection, and per-line readings for slashes, pipes, and plus signs. The `PlaceholderReplacer` class demonstrates a reusable pattern for hiding content during text processing: it stores items during a first pass and restores them after transformations, using configurable delimiters and a cached regex. This pattern is applicable to any text transformation that needs to protect certain substrings from modification (e.g., code blocks in Markdown, URLs in prose). The engine is platform-agnostic and could be extracted as a standalone library for any JavaScript environment.