v0.6.0

v0.6.0 — Major Feature Release

Full changelog from v0.5.1. Jump from v0.5.1 to v0.6.0 (skipped v0.8.0 which was renamed for semantic versioning).

---

New Features

Preference Dialog

• 6-tab GTK3 settings UI (General, Model, Engine, Window, User Dictionary, Shortcuts) — accessible from IBus menu or via ibus-engine-handwrite-chinese --setup

On-Demand Model Download

• Download PP-OCRv6 models (tiny/small/medium) directly from the preference dialog
• Automatic pkexec permission elevation for system-wide install
• Auto-download prompt when selecting a missing model tier

Configurable Keyboard Shortcuts

• Customize all keybindings (ESC, Enter, Backspace, page up/down, cycle theme, open settings) via the Shortcuts tab

User Dictionary

• Per-user stroke→character learning via local SQLite database
• Boosts recognized characters you select in future recognition

TOML Configuration System

• All settings stored in ~/.config/ibus-handwrite-chinese/config.toml
• Overridable via IBUS_HANDWRITE_* environment variables
• Settings: theme, log level, model tier, stroke width, window dimensions, momentum, keybindings, user dict options

Light Theme & HiDPI Support

• Light/dark/auto theme cycling
• HiDPI-aware rendering with per-monitor scale factor

Structured Logging

• Converted to Python logging module with RotatingFileHandler
• Configurable log level and log path via preference dialog

SHA256 Model Verification

• SHA256 integrity check on downloaded PP-OCRv6 models
• Fallback download from mirror when primary source fails

---

Bug Fixes (13 total)

1. Dict index corruption: line.strip() stripped U+3000 (ideographic space) from dict entries, shifting character indices. Fixed with line.rstrip('\n').
2. Confidence pooling: np.mean averaged across all CTC time steps including blank frames, diluting confidence by ~10×. Fixed with np.max (MAX pooling).
3. Stroke line width: Increased from 6px to 8px to match training data distribution.
4. ESC key reliability & Enter pass-through: ESC state machine refined — Enter only commits when candidates exist, passes through otherwise.
5. --test mode keyboard focus: Fixed set_accept_focus(False) blocking GTK keyboard events.
6. Firefox ESC compatibility: ESC now handled regardless of IBUS_RELEASE_MASK press/release state; 150ms debounce prevents double-fire.
7. ESC pause when no text field focused: Removed timer, set accept_focus(True) in do_enable().
8. Auto-pause on non-text area focus loss: Added focus-out-event handler with 50ms debounce for Firefox title bar / desktop clicks.
9. present() skipped on second activation: Always call present() regardless of _focused_since_enable.
10. X11 property flush timing: Call set_accept_focus(True) in do_enable() before present() so X11 flushes the WM_HINTS property.
11. Model download permission error: Download to /tmp instead of root-owned dir; use pkexec cp fallback.
12. Display stroke width ignored preference: Cairo drawing now reads CONFIG["engine"]["stroke_width"] instead of hardcoding.
13. Config cleanup: Removed dead keys model.variant and engine.max_strokes.

---

Packaging

• Debian/Ubuntu/Mint .deb package
• Fedora/openSUSE .rpm package
• Arch Linux PKGBUILD (reference in packaging/)
• Cross-distro bootstrap: bash <(curl -s .../bootstrap.sh) auto-detects distro

---

CI/CD

• 21-job CI matrix: lint, bootstrap, install-deps, GTK write tests across Debian 11/12, Ubuntu 22.04/24.04, Fedora 40/41/latest, Arch Linux, openSUSE Leap/Tumbleweed
• Automated release: builds .deb, .rpm, source tarball, tests packages on all distros, uploads to GitHub Release

---

Recognition Accuracy

Metric	Result
Top-1 accuracy	40/40 (100%)
Average confidence	94.97%
Similar pairs tested	7 groups, 14/14 correct

Validated with 40 real handwriting characters including 7 similar-pair groups (土/士, 未/末, 日/曰, 人/入, 大/太, 已/己, 上/下).

---

Full changelog: see README.md

v0.5.1 — Patch Release

v0.5.1 — Patch Release

Bug Fixes

Auto-pause on non-text area focus loss:
Added GTK focus-out-event handler with 50ms debounce. When the user clicks Firefox's title bar or the desktop background, the handwriting window now auto-pauses instead of remaining stuck in a state where neither IBus nor GTK key events can reach it. Guarded by _has_drawn to avoid confusing startup behavior.

present() skipped on second activation:
Removed the _focused_since_enable guard from _grab_focus_if_needed — present() is now always called. Previously, a spurious XFCE do_focus_in signal before the idle handler ran would skip present(), leaving the window visible but without keyboard focus — ESC and auto-pause silently failed after the first activation cycle.

X11 property flush timing:
Moved set_accept_focus(True) to do_enable() before show_all() and GLib.idle_add. Previously, both calls were in the idle handler — GTK batches X11 WM_HINTS, so the WM still saw accept_focus(False) and denied focus. Now the X11 property is flushed before present(), granting focus reliably on every activation.

Assets

• .deb (Debian 11+/Ubuntu 22.04+/Mint 21+)
• .rpm (Fedora 40+/openSUSE Tumbleweed)
• Source tarball .tar.gz

v0.5.0 — ESC/Enter reliability, root ibus-daemon fix, input group support

v0.5.0 — ESC/Enter reliability, install improvements

Bug Fixes

ESC key reliability & Enter pass-through:

• ESC always handled regardless of state (pause 0→1, close 1→exit)
• Enter only intercepted when candidates exist; otherwise passes through to the application
• Backspace only intercepted in active state; passes through when paused
• --test mode window now receives GTK keyboard events

Install improvements:

• Root ibus-daemon: install.sh kills stale root daemon and prevents re-creation
• Input group: udev uaccess ACL + sg input fallback chain for immediate trackpad access
• DEBIAN_FRONTEND fix: sudo no-op compatibility for noninteractive mode
• DBUS_SESSION_BUS_ADDRESS preservation through su for ibus engine

Wrapper & diagnostics:

• Added tools/diagnose_trackpad.sh — ESC + input group + IBus diagnostics
• Added tests/test_esc_key_routing.py — automated ESC key routing test

CI Improvements

• Recognition test uses venv Python (numpy installed in venv)
• GTK write test skips gracefully when gi (PyGObject) not available
• bootstrap.sh installs python-cairo binding for ONNX stroke rendering

Full Changelog

v0.4.0...v0.5.0

v0.4.1

fix: add display/D-Bus guards + 5s timeout to Restart IBus CI step

Prevents step hanging indefinitely in containers without D-Bus session.

v0.4.0

What's New

• sudo-less install: ./tools/install.sh no longer requires top-level sudo — root privileges are used internally only where needed
• Improved evdev error logging: trackpad diagnostics now print meaningful error messages to stderr
• Better startup diagnostics: engine warns clearly when trackpad initialization fails

Full Changelog

• feat: remove root-required guard from install.sh — use sudo internally for root commands
• docs: update README install commands to reflect sudo-less usage
• fix: improve evdev error logging and trackpad startup diagnostics

v0.3.1

Bug Fixes

🖊️ Light-touch trackpad drawing (ABS_MT_TRACKING_ID)

The engine now tracks ABS_MT_TRACKING_ID (finger-on-surface) instead of requiring BTN_TOUCH (physical click). This means you can draw on your laptop's trackpad with a light touch — no click needed. Many modern trackpads only emit ABS_MT_TRACKING_ID for surface contact and reserve BTN_TOUCH for physical clicks.

⌨️ Ctrl+Space IME switch no longer conflicts

Removed the hardcoded Super+space capture. IBus trigger keys are user-configurable via ibus-setup / dconf, so the engine no longer intercepts them. Previously, pressing Ctrl+Space (or the configured IBus trigger) would be eaten by the engine instead of switching the input method.

🔌 udev ATTRS parent-chain walk

The udev rule now walks the parent device chain to match ATTRS{name}, improving compatibility with trackpads where the name property lives on a parent device node (e.g. I2C-hid buses).

Packaging

📦 Debian / Ubuntu (.deb)

• python3-venv dependency added
• Post-install (postinst): automatically downloads the PP-OCRv6 ONNX model and character dictionary, creates a Python virtual environment with onnxruntime, and installs a wrapper script as the engine binary
• Model path: IBUS_HANDWRITE_PPOCR_MODEL env var supports tiny, small (default), medium

📦 Fedora / openSUSE (.rpm)

• Fully rewritten %post section — same logic as debian postinst: model download, venv creation, wrapper script
• Engine binary installed to /usr/local/share/ibus-handwrite-chinese/ (not /usr/local/bin/)
• Wrapper at /usr/local/bin/ibus-engine-handwrite-chinese routes through the venv for onnxruntime
• Dependencies synced with debian control (removed python3-venv from RPM Requires — it's part of python3-libs on RPM distros)

🚀 Cross-distro bootstrap (bootstrap.sh)

• python3-venv added to detect-deps
• openSUSE zypper install retry with --no-gpg-checks for transient repo timeouts
• Removed duplicate model download (now handled by postinst / install.sh)

CI/CD

✅ CI (ci.yml)

All 21 jobs pass across 5 distros:

• Fixed openSUSE Tumbleweed zypper refresh timeout (cdn.opensuse.org unreachable)
• Fixed Fedora fedora-cisco-openh264 repo timeout — --disablerepo=fedora-cisco-openh264 added
• Fixed cascading artifact name empty — if: always() on Set artifact name step
• 10 GTK writing test containers all green

✅ Release (release.yml)

16 jobs, all green:

• .deb build + verify: fixed missing python3-venv in verify step
• .rpm build + verify: fixed engine path, postinst logic, Fedora openh264 repo
• Test packages across all 10 distro containers pass
• Upload release assets: successful

Maintenance

• Build script tools/build-test-usb-iso.sh for creating a Linux Mint 22 live USB with ibus-handwrite-chinese pre-installed (not in this release, development use)
• README updated with new install paths, requirements, troubleshooting

Assets

• .deb — Debian 11+, Ubuntu 22.04+, Linux Mint 21+
• .rpm — Fedora 40+, openSUSE Tumbleweed
• .tar.gz — source tarball (PKGBUILD reference in packaging/)
• All packages auto-download PP-OCRv6 model on install

v0.3.0

What's New in v0.3.0

🚀 Swipe Gesture Momentum

Velocity-based two-finger swipe with momentum deceleration — swipe faster to advance more pages. Momentum decays at ×0.65 every 50ms, stopping below 0.3 pages.

🖱️ 1-Finger Candidate Drag

Drag one finger in the top 5% trackpad zone to highlight candidates by position; lift to select. Coexists with tap-to-select.

🛡️ Non-Destructive Multitouch

Accidental second finger during a stroke won't destroy the partial stroke — the engine saves and restores stroke state automatically.

🎯 Trackpad Candidate Zone Tuning

Candidate activation zone reduced from 25% to 5% of trackpad Y, giving 95% of the trackpad for worry-free drawing after iterative user QA.

🐛 Bug Fix

• _candidate_buttons → candidate_buttons (7 references had a leading underscore mismatch, silently failing in GLib, preventing all candidate drag gestures)

📝 Documentation

• README updated: swipe momentum, candidate drag, non-destructive multitouch
• Chinese READMEs (Simplified & Traditional) updated with new features
• Acknowledgments section added for PP-OCRv6 (Apache 2.0) and ONNX Runtime (MIT)

🔧 CI/Infrastructure

• Fixed debian metadata, packaging URLs, bootstrap.sh references (ai-space-lab migration)
• Fixed README filenames in release source tarball (zh-Hans-汉 / zh-Hant-漢)

---

Full commit log: v0.2.0...v0.3.0

v0.2.0 — PP-OCRv6 ONNX Unified Engine

v0.2.0 — PP-OCRv6 ONNX Unified Engine

Pure ONNX recognition engine — no Zinnia, no Tegaki, no proprietary engines.

What's New

• PP-OCRv6 ONNX unified engine replacing all legacy backends with a single deep-learning engine
• 18,710 character CJK recognition via PP-OCRv6 MobileNetV3 small model
• 100% top-1 accuracy validated on 40 real handwriting samples
• MAX-pooled confidence scoring fixing the confidence dilution bug in CTC decoder

Package Improvements

• Cross-distro support: .deb (Debian/Ubuntu), .rpm (Fedora/openSUSE), source tarball (Arch)
• ONNX model auto-downloaded on install — not stored in the repository
• pip-based onnxruntime for all distros

Bug Fixes

• Fixed dict index corruption from line.strip() stripping U+3000 ideographic space
• Fixed confidence pooling to use MAX instead of mean across CTC time steps
• Fixed stroke line width from 6 to 8 for training-data alignment
• CI: ONNX model download, pip deps, --break-system-packages fallback, zypper --no-refresh, archlinux python-cairo

Assets

• ibus-handwrite-chinese_0.2.0_all.deb — Debian/Ubuntu package
• ibus-handwrite-chinese-0.2.0-1.fc44.noarch.rpm — Fedora/openSUSE package
• ibus-handwrite-chinese-0.2.0.tar.gz — Source tarball

v0.1.0 Beta

⚠️ Beta Release — tested in CI containers but not yet widely tested on real hardware. Feedback welcome!

Download

Pre-built packages for this release:

Format	File
📦 .deb (Debian/Ubuntu)	ibus-handwrite-chinese_0.1.0_all.deb
📦 .rpm (Fedora/openSUSE)	ibus-handwrite-chinese-0.1.0-1.fc44.noarch.rpm
📦 Source tarball	ibus-handwrite-chinese-0.1.0.tar.gz
📦 AUR	See packaging/PKGBUILD in source

Install

One-liner (any distro):

bash <(curl -s https://raw.githubusercontent.com/vinceyap88/ibus-handwrite-chinese/main/bootstrap.sh)
ibus restart

From .deb (Debian/Ubuntu):

sudo dpkg -i ibus-handwrite-chinese_0.1.0_all.deb
sudo apt install -f  # install dependencies
ibus restart

From .rpm (Fedora/openSUSE):

sudo rpm -i ibus-handwrite-chinese-0.1.0-1.fc44.noarch.rpm
ibus restart

Then select Chinese Handwriting (Simplified) or Chinese Handwriting (Traditional) from your IBus menu.

Features

• macOS-style dark floating handwriting panel with embedded candidates
• evdev touchpad input (works on any touchpad with BTN_TOUCH support)
• Tap-to-select candidates via spatial trackpad mapping
• Two-finger swipe to page through candidates
• ESC to pause/resume/close
• Delete button (tap to remove last stroke, hold to clear all)
• × button always visible to close and restore previous IME
• Drag handle to reposition window
• Auto-reposition to avoid covering active window
• Supports both Simplified and Traditional Chinese (separate IBus engines)
• 幽兰百合 Community v1.1.0 model (9,374 chars) as primary for Simplified + tegaki zh_CN fallback
• Tested in CI across Debian 11/12, Ubuntu 22.04/24.04, Fedora 40/41, Arch Linux, openSUSE Tumbleweed

Changelog (since initial tag)

• Reorganized repo into src/, xml/, icons/, tools/, tests/, docs/ subdirectories
• 幽兰百合 Community v1.1.0 as primary Simplified model (9,374 chars)
• Third-party model stored locally in models/ (not on GitHub), with Gitee-first download priority
• Top bar layout: close (×) always visible, drag handle, delete zone at x > 0.82
• CI tested on 10 distro versions (all passing)
• Esc×2 engine restore fix, pause mode overlay, IBus release-event filtering
• Window auto-reposition to avoid blocking active app
• Packaging: .deb, .rpm, source tarball (built in CI), AUR PKGBUILD reference

Known Limitations

• Beta: only tested on MacBook Pro (bcm5974) by the developer. Wayland popup positioning and SELinux evdev access on Fedora/Arch are untested.
• Accuracy: Simplified Chinese ~80% top-1 on real handwriting (20 common chars). Traditional Chinese uses tegaki zh_TW (2009 model).
• Single character: no multi-character composition yet (planned for V2).
• openSUSE Leap: zinnia library not available in Leap 16.0 default repos.
• Third-party model download: from Gitee (China) — may be slow or unreachable outside China. Falls back to local cache or continues with tegaki only.

Help Test!

If you try this on your hardware, please open an issue with:

1. Your distro and version
2. Laptop model and touchpad type
3. What works and what doesn't

Real hardware reports help us identify issues that CI can't catch (Wayland, SELinux, non-bcm5974 touchpads, etc.).