Yune

Languages: English | 简体中文 | 粵語

The engine that turns your typing into Chinese characters. Type nihao, get 你好. Type nei5 hou2, get 你好 in Cantonese. Built in Rust - native ABI, browser WASM, and CLI paths.

Contents

• What Yune Does
• Why It Exists
• How It Works
• Current Status
• Compatibility
• Performance
• Quick Start
• Quality Checks
• Repository Layout
• Documentation
• Non-Goals
• Contributing
• License

What Yune Does

You type romanized Chinese (Pinyin for Mandarin, Jyutping for Cantonese) on a standard keyboard. Yune converts it to the right Chinese characters in real time.

Under the hood, Yune reads RIME-style dictionary and configuration files for its named targets and supported common-schema behavior. The goal is predictable compatibility with existing RIME schemas when a target has oracle evidence, not a universal all-schema claim.

yune-web.pages.dev — try it in your browser.

Capabilities

• RIME schema and config handling: __include, __patch, custom patches, deploy freshness, schema installation, and schema switching.
• Full input pipeline: speller, selector, navigator, key binder, editor, ASCII composer, chord composer, punctuation, recognizer, translators, and filters.
• Dictionary support: source .dict.yaml, imports, Yune-native compiled table/prism/reverse artifacts, rebuild execution, and fixture-backed ranking verified against the reference engine.
• C ABI compatibility: upstream-shaped default RimeApi and RimeLeversApi, config/context/candidate/session/deploy APIs, dynamic-loader tests, and frontend lifecycle tests.
• TypeDuck profile behavior: fork-only ABI slots exposed through rime_get_typeduck_profile_api(), rich Cantonese dictionary comments, TypeDuck-Web browser evidence, and TypeDuck-Windows backend/profile/IPC smoke evidence.
• Browser runtime: @yune-ime/yune-web-runtime, the yune-web Vite app, multi-schema browser harness (jyut6ping3, cangjie5, luna_pinyin, and more), UI language switching, output standard selection, public demo, and Playwright evidence.
• AI foundation: provider trait, local/mock providers, staged AI rows, privacy policy, separate AI memory, and default-off browser exposure.

Why It Exists

RIME has been the backbone of open-source Chinese input for over a decade. It works well. But it's a large C++ codebase that's difficult to change, test, or embed in modern environments like browsers and mobile apps.

Yune rebuilds the engine from scratch in Rust with three goals:

Run everywhere. The same core engine can be exposed as a native librime-shaped shared library for desktop host experiments, as WebAssembly for browser-based input, or as a CLI tool for testing and benchmarking.

Be testable. Covered behavior is verified byte-for-byte against the relevant RIME-family oracle. Instead of porting C++ code (and inheriting its bugs and assumptions), Yune runs the oracle as a behavior reference: capture what it outputs for a given input, then assert Yune produces the exact same result. This preserves compatibility without cargo-culting a 15-year-old C++ architecture.

Prepare for AI-native input. The engine has a built-in, default-off AI layer. In the future, an on-device language model could suggest completions or corrections alongside traditional dictionary candidates — without slowing down the classic path and without sending your typing to a cloud service.

How It Works

keystrokes  ──►  spelling algebra  ──►  dictionary lookup  ──►  ranking & filtering  ──►  commit text
                    (normalize)          (find candidates)        (sort, deduplicate)        (output)

The pipeline is built from swappable Rust traits — translators, filters, and rankers — rather than a monolithic class hierarchy. Want to plug in a custom ranking model? Implement a trait. Want a different dictionary format? Swap the translator.

The deterministic core is safe Rust. The workspace forbids unsafe code by default, with explicit ABI/FFI exceptions in yune-rime-api and yune-cli.

Current Status

Yune is an active engine project.

• Compatibility baseline: Phase 1 is complete for its captured named target suites. Mandarin luna_pinyin is measured against upstream rime/librime 1.17.0; TypeDuck Cantonese profile behavior is measured against TypeDuck-HK/librime v1.1.2 through the TypeDuck profile. Per the 2026-07-05 D-31 amendment, canonical jyut6ping3 candidate ordering, segmentation, fallback, and completion now use upstream rime/librime 1.17.0 plus pinned rime/rime-cantonese; M58 completed the fresh canonical capture at f780410c, including the user-specified zijiguk / 諮議局 case, which returns 諮議局 first and did not produce a canonical fix. The M55 expanded oracle sentence fixtures also surfaced known, recorded gaps. Current reconciled evidence repairs the final 37/59 candidate text/order, but some single-letter pages and intermediate long prefixes still differ in candidate text, comments, or preedit — disclosed correctness debt, not silent drift. yune-web has real in-browser validation (TypeDuck-Web); the TypeDuck-Windows backend has package/header, profile-ABI, and stock real-server IPC compatibility smoke through the named profile accessor, while interactive TSF typing and visible candidate UI remain Phase 2 product/frontend work.
• Current work: milestones M38-M58 are complete, with M55 closed under a 2026-07-04 corrective re-baseline: the benchmark now reads context after every keypress (the interactive shape), three pre-corrective closeout mechanisms were identified as measurement artifacts and reverted, and the standing regression gate (startup, session, eight Track A key rows, Track A peak memory, win rows locked <1.00x, TypeDuck Track B absolutes) is green twice on the honest metric and re-run green at M58 closeout. M58 also fixed current yune-web TypeDuck/profile reachability for beingo / 畀 and zi / 諮 by short-input profile-ranked paging, without first-page promotion. The current-main M59 Mac diagnostic finds six aggregate Track A wins and eleven losses; the apparent 37/59 aggregate wins are not behavior-normalized, while n/zh execute 8.682x/4.092x librime's instructions. This is a lane-specific bounded-gap result, not a blanket claim that any row set is faster than librime.
• Public demo: yune-web is deployed at https://yune-web.pages.dev. It's a Yune engine demo, not a claim that browser-level performance is solved.
• AI posture: the AI layer exists but is default-off, local-only in the web harness, and outside the classic deterministic input path.

See docs/roadmap.md for the detailed milestone plan.

Compatibility

Yune's compatibility is target-driven, not checklist-driven.

Reference engines (the "oracles" that define correct behavior):

• Default core oracle: upstream rime/librime 1.17.0 (33e78140250125871856cdc5b42ddc6a5fcd3cd4).
• Canonical Cantonese/Jyutping candidate oracle: upstream rime/librime 1.17.0 plus pinned rime/rime-cantonese; M58 records the completed Yune-facing id/provenance split for this lane.
• TypeDuck profile oracle: TypeDuck-HK/librime v1.1.2 (74cb52b78fb2411137a7643f6c8bc6517acfde69) for profile/display/comment behavior, multilingual dictionary lookup payloads, fork-only ABI/profile controls, and historical fixture-backed profile candidate guards. The preferred future TypeDuck multilingual profile id is jyut6ping3_typeduck, after M58's completed schema/profile blast-radius audit; no split landed, so it remains pending explicit user sign-off.

Rules:

• Preserve upstream-observable behavior for named targets.
• Isolate TypeDuck fork behavior behind the TypeDuck profile surface; do not use fork v1.1.2 ordering to define canonical jyut6ping3 candidates.
• Add librime features only when a named target needs them.
• Keep expected bytes non-circular: always capture them from the relevant oracle, never derive them from Yune itself.

Default rime_get_api() remains upstream-shaped. TypeDuck fork-only ABI slots are exposed exclusively through rime_get_typeduck_profile_api().

Performance

The standing native Windows gate is intentionally measured same-run against upstream rime/librime 1.17.0, with the context read after every keypress (the shape real frontends have; earlier batch-shaped numbers are not comparable and the pre-corrective M55 closeout numbers were measurement artifacts — see the corrective record). This is not a claim that every benchmark row ranks identically to librime or that browser performance is solved.

Signed Windows Track A same-run ratios (M55 corrective gate run D, 2026-07-04; lower is better) remain the gate:

• Faster than librime: startup 0.895x and session 0.864x (run-noisy), zhongguo 0.255x, cszysmsrsd 0.381x, and zybfshmsru 0.564x — the three win rows are locked <1.00x in the standing gate.
• Slower than librime, bounded and guarded: the short keys hao 1.574x (+9 us), ni 2.433x (+25 us), n 2.636x (+34 us) — tens of microseconds, imperceptible while typing — and the sentence rows: 37-char 1.913x (+273 us) and 59-char 1.528x (+352 us), both improved ~35% from the pre-M55 3.05x/2.25x by real graph-work reductions.
• Memory: the shipping default keeps the Luna poet payload on the heap (Track A peak 185.7 MB vs librime peer 13.5 MB) because the latency ceilings bind. M55's historical YUNE-POET/2 byte-backed opt-in (YUNE_POET_BYTE_BACKED=1) measured 113.2 MB with identical candidates but cost 4.6x/3.2x on the sentence rows. M59's sentence/phrase index extends the current artifact to YUNE-POET/3; /2 is deliberately rejected and rebuilt, so the M55 numbers remain historical rather than being silently attributed to /3. The current deployed /3 byte-backed control emits zero candidates on all 99 prefixes; behavior must be recovered before any memory or speed claim, followed by incremental/lazy indexing rather than an assumed direct scratch port. The browser luna_pinyin gap (64 MiB vs My RIME 16 MiB) is a separate lane. The Jyutping product path is not a like-for-like comparison (TypeDuck multilingual dictionary); M47 byte-backed the shipping keyboard profile to about 67 MB working set / 22 MB private.
• Track B TypeDuck-profile rows and browser startup are separate evidence lanes, not upstream-librime native comparisons. The M58 closeout Track B guard proof is the final-pass ratchet (335.823 us on the 50+ key product row, ceiling 347.975 us), and it remains TypeDuck/profile product-path evidence rather than canonical rime-cantonese candidate-oracle evidence.

The current-main Mac packet at afb7079b is diagnostic, not a new gate. Yune wins 6/17 aggregate Track A rows and loses 11. Its 37/59 aggregate ratios are 0.399x/0.205x, but candidate-text-different prefixes dominate those wins; the text-matched sensitivity is 1.420x/1.204x. n/zh use 8.682x/4.092x librime's instructions. Allocator and platform effects are partial, and exact cross-platform attribution remains open.

Current reports:

• docs/reports/yune-vs-librime-performance.md
• docs/reports/yune-vs-librime-root-cause-analysis.md
• M59 post-fix macOS root-cause packet

Quick Start

Prerequisites:

• Rust 1.76 or newer
• Node.js and npm (for the browser harness and TypeScript runtime)
• Emscripten (only if building the WASM artifact locally)

Build and test:

cargo build
cargo test --workspace

Feed keystrokes directly to the core engine:

cargo run -p yune-cli -- run "nihao "

Run against real RIME data through the full ABI path:

cargo run -p yune-cli -- frontend \
  --shared-data-dir ./path/to/rime-data \
  --user-data-dir ./tmp/yune-user \
  --schema luna_pinyin \
  --sequence "nihao "

Run the browser demo locally:

npm --prefix apps/yune-web install
npm --prefix apps/yune-web run build
npm --prefix apps/yune-web run start

For browser validation work, start with apps/yune-web/e2e/yune-browser-smoke.md.

Quality Checks

Run these before merging significant changes:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
npm --prefix packages/yune-web-runtime test
npm --prefix packages/yune-web-runtime run build

Browser-visible claims need Playwright or equivalent real-browser evidence.

Repository Layout

Path	What's In It
crates/yune-core	The engine: dictionary lookup, spelling algebra, candidate ranking, filters, user dictionary, AI staging.
crates/yune-rime-api	C ABI adapter: exposes the engine through the supported librime-shaped default ABI and named profile surfaces.
crates/yune-cli	Developer CLI: feed it keystrokes, get JSON output for testing and debugging.
packages/yune-web-runtime	TypeScript wrapper for the WASM build.
apps/yune-web	Browser demo app — the public face of the project.
docs	Roadmap, architecture decisions, conventions, reports.
fixtures	Deterministic test fixtures (expected engine output for given inputs).
scripts	Build helpers, benchmarks, oracle-capture tooling.

Documentation

• docs/conventions.md — architecture, stack, coding rules, testing conventions, ABI rules, integrations, and current risks.
• docs/roadmap.md — active roadmap and milestone gates.
• docs/decisions.md — decision log and standing principles.
• docs/requirements.md — requirement IDs and status.
• docs/ledgers/fork-parity-ledger.md — Cantoboard and TypeDuck fork deltas versus upstream.
• docs/plans/ — active, reference, and completed execution records.

Non-Goals

Equally important as the goals — these are things Yune intentionally does not do:

• Bit-for-bit librime internals or full C++ plugin ABI parity.
• A broad librime feature checklist without a named target.
• Widening the default upstream RimeApi for TypeDuck-only behavior.
• Cloud inference as a hard dependency.
• Remote AI providers without explicit privacy and product gates.
• Claiming application/browser performance wins from native engine evidence.

Contributing

Bug reports, feature proposals, and pull requests are welcome. For anything that affects behavioral compatibility, include oracle-captured evidence (real RIME output against the same input — expected values must not be derived from Yune itself). Start with docs/conventions.md for architecture and coding rules.

License

Original code is MIT. Third-party schemas, dictionaries, fixtures, generated data, and provenance materials keep their upstream licenses — see THIRD_PARTY_NOTICES.md.