pangu.js: CJK and Latin Text Spacing, With On-Device AI for the Ambiguous Cases

The spacing argument pangu.js is designed to end

The premise is narrow and stated bluntly: when Chinese characters sit directly against half-width Latin letters, digits or symbols, the two scripts run together, and someone has to insert the space. pangu.js is that someone. It targets people who write Chinese, Japanese or Korean mixed with English or numbers, and who would otherwise fix the spacing by hand in every paragraph. The README frames the inserted whitespace as 盤古之白, the space that separates full-width and half-width characters. That framing tells you the project is opinionated: it has a preferred typographic result and it applies that result without asking.

The scope is wider than a single npm package. The README lists official support for pangu.js itself plus pangu.py, pangu.go, pangu.java and pangu.space, and community ports for Clojure, Dart, Elixir, Objective-C, PHP, Ruby, Rust, Swift and a pangu.skill. So the same spacing rule has been reimplemented across runtimes, which matters if your stack is not JavaScript. The repository you are reading about is the TypeScript original, and it is the one that also ships the Chrome extension and the CLI.

Two spacing engines: regex rules and a local model

The core mechanism is a text transformation. `spaceText()` takes a string and returns it with spaces inserted between CJK and ANS (the package description defines ANS as alphabetical letters, numerical digits and symbols). The README gives a worked example: `當你凝視著bug，bug也凝視著你` becomes `當你凝視著 bug，bug 也凝視著你`. On the browser side there is a second layer: `spaceNode()` operates on a DOM node, and `autoSpacePage()` consumes a stream of DOM mutations through a MutationObserver so dynamically rendered content gets spaced too. That is a real design decision, not a detail, because a page that renders after load would otherwise stay unspaced.

The third layer is the AI Spacing feature in the Chrome extension. The README is explicit that regex rules cannot distinguish semantic nuances, and gives two pairs. For `+`, `這裡沒有18+的內容` means "or more" and should become `這裡沒有 18+ 的內容`, while `Switch 2+瑪利歐賽車世界同捆組` joins two things and should become `Switch 2 + 瑪利歐賽車世界同捆組`. For `-`, a negative number and a separator pull in opposite directions. To resolve those, the extension calls Chrome's built-in Prompt API, which runs Gemini Nano on the device. According to the README, nothing leaves the machine and the feature is free. The prompt tuning is itself described as automated: a skill called prompt-experiments proposes a change, tests it against the real Gemini Nano in Chrome, and searches for new approaches when progress stalls.

Installing pangu.js and running a first real spacing pass

The npm package is the entry point for developers. The README recommends an exact install rather than a caret range, which is a sensible default for a tool whose output is text you may diff.

npm install pangu --save-exact

In Node, import the default export and call `spaceText()` on a string, or `spaceFile()` on a path. The README's Node example uses `await pangu.spaceFile('/path/to/text.txt')`, so `spaceFile` returns a promise.

import pangu from 'pangu';

const text = pangu.spaceText('與PM戰鬥的人，應當小心自己不要成為PM');
// text = '與 PM 戰鬥的人，應當小心自己不要成為 PM'

In the browser, import from `pangu/browser`. The README stresses this: it is the DOM-aware build with `spaceNode()` and `autoSpacePage()`, with matching TypeScript types, and it resolves correctly across bundlers. Importing the root package in a browser bundle is the mistake the README is warning you away from.

import pangu from 'pangu/browser';

pangu.spaceNode(document.getElementById('main'));

document.addEventListener('DOMContentLoaded', () => pangu.autoSpacePage());

If you would rather not install anything, the CLI is the fastest way to see the output. Piping text in works, and `-t`, `-f` and `-c` cover string, file and check modes. The `-c` flag is the interesting one: it reports whether a correction was needed and returns exit code 1 when it was, which makes it usable as a CI gate.

pangu "不能信任那些Terminal或Editor用白底的人"
pangu -t "你在每個commit裡修改的程式碼越多，你在code review時被發現的錯誤就會越少"
pangu -f path/to/file.txt
pangu -c "盤古新聞網：工程師會議中默不作聲，PM恐成最大贏家"; echo $?

The README shows the `-c` run printing `Corrected: 盤古新聞網：工程師會議中默不作聲，PM 恐成最大贏家` and then `1`. For the Chrome extension, installation is the Web Store listing linked from the README; there are no build steps for users. The repository also carries an `examples/` directory with `verify-browser.html`, `verify-cli.js`, `verify-commonjs.js`, `verify-esm.mjs` and `verify-types.ts`, which is where the maintainers appear to check that each consumption path actually works.

Markdown is the wrong input, and the README says so

The clearest limitation is stated in the README in bold: you SHOULD NOT use pangu.js to space Markdown documents, because the library is designed for HTML webpages and plain text without markup. It links issue #127 for the reasoning. The practical consequence is that a Markdown source file is not a safe input. Spacing rules that are correct in prose can land inside link syntax, code spans or front matter, and the library has no parser to tell those regions apart. If your content pipeline is Markdown-first, you need to space the rendered or extracted text, not the source.

The second limitation is the one the AI Spacing feature exists to work around. Symbol spacing is context-dependent, and the deterministic rules cannot resolve it. The extension's answer is an LLM call through Chrome's Prompt API, which means the semantic path depends on Gemini Nano being available in that Chrome build. The README does not describe a fallback for browsers where the Prompt API is missing, and it does not document a way to run the semantic judgment outside Chrome. So the library gives you deterministic spacing everywhere JavaScript runs, while the smarter behavior is confined to one browser's extension surface. That is an asymmetry worth knowing before you plan around it.

How pangu.js compares with a CSS text-autospace approach

The obvious alternative is not another library but the browser: CSS `text-autospace`, which asks the rendering engine to insert the space at layout time. The difference in approach is fundamental. pangu.js rewrites the text, so the space becomes a real character in the string, the DOM, the file and anything downstream that copies it. CSS spacing leaves the underlying text untouched and only affects how it is drawn.

That distinction decides most adoption questions. If you need the spaced form in a copied selection, in a `spaceFile()` output, in a CLI pipeline or in a CI check, you need the characters, and CSS cannot give them to you. If you only care how a page looks and you control the stylesheet, CSS avoids mutating content and avoids the Markdown problem entirely. pangu.js also spans environments CSS never reaches: Node scripts, file processing, and a Chrome extension that spaces pages you do not own.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-15, one day before this was written. The package version in `package.json` is 10.1.1, and the README points to `CHANGELOG.md` for release history. No releases were retrieved for this article, so the changelog is the place to look for what changed between versions.

Licensing is MIT, which permits commercial and closed-source use with the usual attribution and warranty terms; that is a summary of the licence identifier, not legal advice. The real upgrade cost sits in the output. Because the library's job is to change text, a version bump can change the text you produce, and any snapshot test, golden file or copied fixture that contains spaced CJK will need review. The `-c` flag and its exit code give you a way to detect drift in a pipeline, and the `examples/verify-*` files show the maintainers testing the CommonJS, ESM, browser and type consumption paths separately, which is a hint that the packaging surface is where breakage tends to appear.

Editorial conclusion

Adopt pangu.js if you publish Chinese, Japanese or Korean text next to Latin letters, digits or symbols and want the spacing handled in a build step or in the browser. Do not reach for it on Markdown or other markup sources, and do not expect it to be the last word on `+` and `-`, because the README itself says regex rules cannot settle those. Before you commit, run `pangu -c` on a sample of your own copy and read the exit code, then check whether the AI Spacing extension path is available on the Chrome version you target.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vinta/pangu.js on GitHub