soan-professional-cli

soan-professional-cli

soan-professional-cli is a TypeScript CLI for generating Soan images with reproducible Professional controls on top of the Soan v1.1.0 compatibility renderer.

Installation

npm install -g soan-professional-cli
soan --version

The package provides three equivalent command names:

• soan
• soan-cli
• soan-pro

Quick Start

soan \
  --text "［加］/な" \
  --seed 42 \
  --generated-at 2026-06-29T00:00:00.000Z \
  --gamma 1.1 \
  --output ./sample.jpg \
  --metadata-output ./sample.json \
  --force

--metadata-output writes the canonical reproducibility sidecar JSON. JPEG output also receives the same Professional metadata as APP1 XMP when it fits.

Chuko-Wabun UniDic

--old-japanese / --kobun uses MeCab with Chuko-Wabun UniDic when mecab is available and the dictionary is provided by --mecab-dic or SOAN_MECAB_DIC. The dictionary is distributed separately from the npm package and is licensed under CC BY-NC-SA 4.0.

soan dict install
soan dict path

The command downloads the release asset, verifies the pinned SHA-256, checks the archive paths, and extracts the dictionary. By default, the dictionary is installed under the user data directory. Use soan dict update to replace the local copy with the pinned release, and soan dict path to print the dictionary path for scripts. --output <dir> remains available when you need a project-local or CI-specific dictionary parent directory.

soan \
  --text "けふ/こそ" \
  --kobun \
  --seed 5 \
  --output ./kobun.jpg \
  --metadata-output ./kobun.json \
  --force

Features

• full-width bracket Pro notation: ［加］な, ［八良］ぬ, and ［ID4867］ (half-width [] and full-width ／ stay literal in the rendered text)
• slash boundaries: はな/の
• deterministic glyph/layout selection with --seed; when omitted, a seed is auto-generated and reported (Seed: <n> on stderr) so the same glyph combination can be reproduced later
• byte-level reproducible JPEGs when --generated-at is fixed
• gamma post-processing with --gamma
• v1.2 typesetting (--layout v1.2, default) uses local reselection in the renderer: when a non-final line has trailing space and a glyph has multiple candidates, seeded randomness selects an alternate candidate and the layout is rebuilt. A pass is adopted only when total trailing gap decreases; the process stops at zero gap or after --layout-attempts passes (default 4, range 1-16). --layout v1.1 remains a single render without reselection.
• layout controls: --num-lines, --char-spacing, --line-spacing, --page-width, and --page-height
• paper-texture layout with --texture-image-layout-mode and --lines-per-page (default 10): sizes the canvas to the paper texture's natural dimensions and centers the text block on it
• --center-page centers the text block on the page (designed for --num-lines with --page-width / --page-height)
• glyph borders with --border
• image text confirmation with --print-image-text (also recorded as imageText in the metadata sidecar)
• sample text rendering with --sample-text (Nakajima Atsushi, "Sangetsuki")
• MeCab / Chuko-Wabun UniDic analysis with --old-japanese / --kobun
• manual glyph offsets with --manual-positions
• sidecar reproducibility metadata with --metadata-output
• JPEG XMP embedding and PNG output

Metadata

The sidecar JSON written by --metadata-output is the canonical reproducibility record for v2.0.0. JPEG output also receives the same Professional metadata as APP1 XMP when it fits.

For v1.2 layout, the layout metadata has this shape:

{
  "version": "v1.2",
  "attempts": 4,
  "passes": 1,
  "trailingGap": 0
}

attempts is the configured maximum number of local reselection passes, passes is the number actually executed, and trailingGap is the final gap of the adopted layout. --layout v1.1 records the same fields with no reselection passes.

Breaking changes in v2.0.0

• v1.2 now uses renderer-local glyph reselection instead of the v1.x CLI approximation that rendered the entire document repeatedly with derived seeds.
• Determinism is preserved for the same --seed, input, and options, but output is not compatible with v1.x when the seed is the same.
• The layout metadata changed from { version, attempts, chosenAttempt, chosenSeed, trailingGap } to { version, attempts, passes, trailingGap }. chosenAttempt and chosenSeed are removed because there is one seed and no separately selected full-document attempt.

Development

From the repository root:

pixi run install
pixi run check

Useful release checks:

cd packages/cli
npm run test:e2e
npm pack --dry-run
npm publish --access public --dry-run

Release tags are published by GitHub Actions. npm publication uses npm Trusted Publishing with GitHub Actions OIDC, and GitHub Packages publication uses the workflow GITHUB_TOKEN.

Notes

• PixiJS interactive editing is not part of the v2.0.0 CLI package.
• When a Pro glyph directive is present, the compatibility renderer sets the effective renmenPriority to 0 for that render and records that value in metadata.
• The CLI package is MIT licensed. Chuko-Wabun UniDic is distributed separately under CC BY-NC-SA 4.0.

Acknowledgements

This package builds on Soan, a CODH JavaScript library for rendering modern Japanese text with old movable type images.

The CLI control surface is based on Soan Professional, an extended Soan workflow that adds bracket-based jibo/glyph controls, slash boundaries, classical Japanese analysis, seed control, glyph position adjustment, and glyph search/replacement.