BilineIME

Type Chinese. Glance at English. Stay in flow.

Core model	Type pinyin, browse Chinese candidates, preview English only when it is ready.
Runtime lane	Developer/tester lane with BilineIMEDev.app, Settings, broker, and local host smoke.
Current boundary	Chinese candidate ranking, paging, raw cursor editing, and commit state remain source of truth.

Product Model

BilineIME has one primary interaction model:

1. Type Chinese pinyin.
2. Browse Chinese candidates.
3. Optionally inspect English preview for visible Chinese candidates.
4. Commit either the Chinese candidate or its ready English preview.

The boundary is strict:

• Chinese candidate generation, ranking, paging, and commit state remain the source of truth.
• English preview is an overlay, not a separate input mode.
• Turning bilingual capability off yields a plain Chinese-first pinyin workflow.
• Translation preview must never block Chinese typing, browsing, raw cursor editing, or commit.

Interaction Highlights

Workflow	Behavior
Candidate browsing	=/] expand and move down while preserving the intended column across short rows; -/[ move up and collapse at the top.
Layer switching	Shift+Tab switches between Chinese commit and ready English commit for the highlighted cell.
Uppercase Latin	Shift+letter inserts uppercase Latin directly when idle; while composing it stays in marked composition as an uppercase Latin segment, with marked preedit showing parser syllable or initial spaces around it.
Raw pinyin cursor	Option+←/→ moves by pinyin block; Command+←/→ jumps to start/end.
Composition deletion	Option+Backspace deletes one pinyin block; Command+Backspace deletes to the raw cursor start.
Candidate panel	The custom AppKit panel shows only candidates in candidate mode; raw-buffer-only composition keeps a compact raw buffer fallback.

Plain ←/→ only browse candidates when the raw pinyin cursor is at the end of the composition. If the cursor is in the middle, those keys continue moving the raw pinyin cursor inside the marked text instead of touching the host document.

What Ships Today

• Native macOS InputMethodKit input method app: BilineIMEDev.app.
• SwiftUI Settings app with Translation, Input Settings, Appearance, and Status.
• Rime-backed simplified and traditional schemas with user dictionaries.
• Rime language-model support through librime-octagram, with bundled grammar model assets in the dev/tester package.
• Custom AppKit bilingual candidate panel with compact and expanded presentation.
• Inline marked-text preedit with raw pinyin cursor editing.
• Broker-mediated Settings/IME coordination through BilineBrokerDev, BilineCommunicationHub, shared configuration storage, and shared credential storage.
• Alibaba Cloud translation behind user-managed shared Keychain credentials.
• Unified dev lifecycle through bilinectl, with Make targets as thin wrappers.
• Local real-host smoke harness for TextEdit: candidate-popup, browse, commit, settings-refresh, and full.
• Unsigned tester packages for install, safe uninstall, and deep clean.

Current Status

Core model	Established. Chinese-first bilingual preview is the fixed product boundary.
Dev lane	Usable. Install, remove, reset, diagnose, broker coordination, tester packaging, and host smoke are supported workflows.
Host smoke	Baseline is green for candidate popup, browsing, commit, and safe-boundary settings refresh. Hard editing cases still need broader real-host coverage.
Release lane	Paused. The reserved BilineIME target remains, but notarized release packaging is not currently supported.

Quick Start

Full machine handoff lives in docs/development-handoff.md. The shortest dev path is:

make bootstrap
make project
make test
make build-ime
make install-ime

Useful day-to-day commands:

make build-settings
make build-broker
make remove-ime
make reset-ime
make prepare-release-env
make diagnose-ime
make dev-pkg
make verify

Notes:

• Build products go to ~/Library/Caches/BilineIME/DerivedData.
• BilineIME.xcodeproj is generated from project.yml; regenerate it locally instead of committing it.
• Do not launch the IME app directly with open; let imklaunchagent own activation.

Install, Enrollment, Smoke

The repository treats host verification as three separate phases:

1. Install bundles.
2. Manually enroll the input source if macOS still requires it.
3. Run source-ready host smoke.

Use these entrypoints:

make install-ime
make smoke-ime-host-check
make smoke-ime-host-prepare
make smoke-ime-host SMOKE_SCENARIO=full

What each step means:

• make install-ime installs the dev IME, Settings app, broker, and local diagnostics state. It does not force-enable the input source.
• make smoke-ime-host-check reports readiness as bundle-missing, source-missing, source-disabled, source-not-selectable, source-not-selected, or ready.
• make smoke-ime-host-prepare only opens System Settings and prints remediation. It never clicks Allow or enables the source for the user.
• make smoke-ime-host is the only supported automated real-host entrypoint. It is local-only, never a CI gate, and drives exactly one TextEdit session.

The default real-host flow is still manual: the user selects BilineIME Dev, focuses the host, types, edits raw pinyin, browses, commits, and reports the result.

Storage And Coordination

The IME and Settings app coordinate through the broker:

• BilineBrokerDev is the user-scoped coordination process.
• BilineCommunicationHub is the shared client facade used by both the IME and the Settings app.
• Shared configuration is persisted through the broker-backed configuration store.
• Alibaba credentials are persisted through a shared Keychain-backed vault, with legacy file fallback retained only for migration/recovery.
• Engine-sensitive settings apply only at safe lifecycle boundaries, not in the middle of live composition.

Tester Packages

For prerelease tester distribution:

make dev-pkg

This produces three unsigned packages in build/dist:

• BilineIMEDev-<version>.pkg
• BilineIMEDev-Uninstall-<version>.pkg
• BilineIMEDev-DeepClean-<version>.pkg

The tester lane installs BilineIMEDev.app, BilineSettingsDev.app, BilineBrokerDev, and the broker LaunchAgent into trusted test locations. Gatekeeper will still block first launch of unsigned packages; see docs/development-handoff.md for exact install guidance.

Documentation Map

development handoff	New machine setup, lifecycle, smoke, credentials, failure recovery.
architecture	Product model, module boundaries, broker/storage, verification model.
engineering standards	Coding, testing, and host-smoke engineering rules.
acceptance checklist	Delivery, behavior, install, and verification checklist.
IME risks	Known risks, gaps, and next high-value host smoke coverage.
ADRs	Architectural decisions and historical context.

Roadmap

Now

• Keep simplified and traditional Rime schemas stable.
• Keep Chinese candidate quality and consumed-span behavior correct.
• Keep raw pinyin cursor editing reliable in marked text.
• Keep Shift+ASCII letter aligned with Apple Chinese input behavior: direct uppercase Latin insertion while idle, marked-composition uppercase Latin segments while composing, and continued pinyin composition after those segments. Marked preedit may show parser syllable or abbreviated-initial spaces, but raw input and committed candidate text stay unspaced.
• Keep broker-backed Settings/IME coordination boring and predictable.
• Keep the unsigned tester lane usable for prerelease installs and removals.

Next

• Expand host smoke beyond the current baseline into punctuation, raw-buffer behavior, editing keys, Shift+Tab persistence, phrase/tail commits, and mixed Chinese/Latin stress cases, including uppercase Latin segments followed by more pinyin inside composition and marked preedit syllable/initial spacing.
• Turn current engine-side future toggles into real behavior where appropriate, especially smart spelling and emoji candidates.
• Tighten docs and diagnostics around source enrollment edge cases after install, reset, and deep clean.

Later

• Restore a supported release packaging lane for the reserved BilineIME target.
• Add broader host coverage beyond TextEdit once the baseline lane stays stable.
• Revisit richer release/distribution UX after the dev/tester lane no longer needs frequent recovery guidance.

Repository Policy

BilineIME is GPL-3.0 licensed. Runtime dependencies, bundled data, and major architecture decisions should stay documented and attributable. Generated build artifacts and local project files remain untracked.