Keyman / per-language keyboard integration (BL-16524)

[hatton]

---

This change is 

Devin review

[greptile-apps]

Greptile Summary

This PR introduces a full per-language keyboard integration for Bloom, covering both the edit view (live keyboard switching while typing) and the Collection Settings Book Making tab. The C# side adds a KeyboardResolver cascade (Off → pinned System → pinned KMW → Automatic), a CollectionKeyboardCache for offline keyboard storage, a KeymanCloudClient for the Keyman API, OsKeyboards for Windows input-language switching via WM_INPUTLANGCHANGEREQUEST, and two new API controllers. The TypeScript side adds keymanWebIntegration.ts (engine loading, keyboard attachment, OSK visibility management) and a new KeyboardSection React component in the settings dialog.

• New Keyboarding/ subsystem (C#): All five new classes are fully unit-tested and cleanly dependency-injected; network calls are always on background threads; OS-keyboard enumeration is correctly marshalled to the UI thread only where required.
• New keymanWebIntegration.ts: Engine loads lazily on first KMW field focus; a bounded poll handles the engine's lazy code download; the oskHideIsProgrammatic flag correctly distinguishes programmatic from user-initiated OSK hides.
• Settings UI (KeyboardSection.tsx): Uses useMountEffect, handles offline gracefully, and posts keyboard changes immediately to the server for restart-flag tracking.

Important Files Changed

Filename	Overview
src/BloomExe/Keyboarding/KeyboardResolver.cs	New class implementing the keyboard cascade. Well-structured with injected dependencies for testability; background fetch is properly isolated via a _runInBackground delegate so the UI thread is never blocked.
src/BloomExe/Keyboarding/KeymanCloudClient.cs	New Keyman API client using a shared static HttpClient. JSON parsers are pure static methods for isolated unit testing. Blocking .Result calls are safe since the client is always called from background threads.
src/BloomExe/Keyboarding/CollectionKeyboardCache.cs	New on-disk keyboard cache. Writes are atomic (temp-file-then-rename), manifest is written last to ensure integrity, and partial downloads never leave corrupt state.
src/BloomExe/web/controllers/KeyboardingConfigApi.cs	New edit-view keyboard API. fieldFocused correctly runs on the UI thread; network/download work is dispatched to Task.Run via the resolver's background delegate.
src/BloomExe/web/controllers/CollectionSettingsApi.cs	Adds two settings-dialog keyboard endpoints. keyboardsForLanguage correctly runs off the UI thread; minor unsynchronized double-check in EnsureKeyboardServicesBuilt (see comment).
src/BloomBrowserUI/bookEdit/js/keymanWebIntegration.ts	Browser-side KMW integration. Engine loads lazily; oskHideIsProgrammatic flag correctly distinguishes programmatic from user-initiated hides. Unhandled rejections are caught by .catch in the caller.
src/BloomBrowserUI/react_components/keyboardSection.tsx	New settings UI for per-language keyboard selection. Uses useMountEffect correctly and handles the offline case gracefully.
src/BloomExe/Keyboarding/OsKeyboards.cs	New OS keyboard enumeration and activation using WM_INPUTLANGCHANGEREQUEST. TIP residual risk is clearly documented. All methods are correctly UI-thread-only.
src/BloomExe/Collection/CollectionSettingsDialog.cs	Adds PendingKeyboardSelections and wires it through UpdateLanguageSettings. EnsureKeyboardCachedInBackground fire-and-forgets a pre-warm download for pinned KMW keyboards on OK.
src/BloomTests/Keyboarding/KeyboardResolverTests.cs	Comprehensive resolver tests covering all cascade branches and background fetch side effects with fake collaborators.

_{Reviews (2): Last reviewed commit: "Run the Book Making keyboard cloud searc..." | Re-trigger Greptile}

[greptile-apps]

All new keyboard strings carry translate="no"

Every one of the ten new <trans-unit> entries — "Keyboard for {0}", "Automatic", "Off", "Currently: {0}", "Installed input methods", "Keyman (online) keyboards", etc. — has translate="no". That attribute tells Crowdin to skip them, so they will never be translated into any other language. Comparable existing strings in this file (e.g. CollectionSettingsDialog.BookMakingTab.DefaultFontFor) do not carry this attribute. If the intent is to ship these strings un-translated initially and add translations later, the translate="no" needs to be removed when they are ready for Crowdin pickup.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[hatton]

[Devin] Bug: Keyboard font file changes in Team Collections are not detected for syncing (TeamCollection.cs:903)

The file-monitoring list for Team Collection sync uses Directory.EnumerateFiles(folderPath, "*") without SearchOption.AllDirectories, so files inside subfolders are omitted. Changes to cached keyboard fonts in the Keyboards/fonts/ subfolder are therefore never included in the sync checksum, and teammates never receive an updated font.

Suggested fix: enumerate with SearchOption.AllDirectories for the Keyboards folder (or the relevant monitored roots).

[hatton]

[Devin] Investigate: Language-tag replacement removed data-languageTipContent; context controls now compute the name at render time (CanvasElementContextControls.tsx:70-72)

The old AddLanguageTags stamped data-languageTipContent on each editable and this component read it directly. The new code calls getLanguageDisplayName(editable?.getAttribute('lang')) → theOneLocalizationManager.getLanguageName(langCode) at render time instead. Believed functionally equivalent, but the lookup path and timing changed. Worth verifying the displayed names still match the old behavior for CJK and other non-Latin scripts.

[hatton]

[Devin] Investigate: Settings dialog blocks the UI thread with a synchronous HTTP call to the Keyman cloud API (CollectionSettingsApi.cs:675)

GetKeyboardsForLanguage calls _keymanCloudClient.SearchKeyboardsForLanguage(tag), which does s_httpClient.GetAsync(url).Result. The endpoint is registered with handleOnUiThread: true, so the WinForms UI thread blocks for up to the 5s HttpClient timeout — the settings dialog freezes while the cloud list loads (worst case when offline). The OS-keyboard enumeration genuinely needs the UI thread, but the cloud search does not; consider moving just the cloud search off-thread.

(Greptile flagged the same line as P1.)

[hatton]

[Claude Opus 4.8] Consulted Devin on 2026-07-10 19:04 UTC up to commit 19f7fb7. Findings (1 Bug, 2 Investigate) mirrored as inline review threads; Informational items skipped.

[hatton]

[Claude Opus 4.8]

Bug: HandleGetLanguageNames throws NRE when no book is selected

src/BloomExe/web/controllers/CollectionSettingsApi.cs:473 dereferences _bookSelection.CurrentSelection with no null guard:

x["language1Name"] = _bookSelection.CurrentSelection.CollectionSettings.Language1.Name;

If settings/languageNames is requested while no book is selected, this throws System.NullReferenceException and pops the "Bloom had a problem" dialog.

Repro (observed at runtime): switch collections mid-session (workspace/openCollection). Immediately afterward Bloom is on the Collections tab with CurrentSelection == null; a request to settings/languageNames in that window crashes:

System.NullReferenceException: Object reference not set to an instance of an object.
  at Bloom.web.controllers.CollectionSettingsApi.HandleGetLanguageNames(ApiRequest request)
     in .../CollectionSettingsApi.cs:line 473

Discovered while runtime-checking the canvas-element context control on a CJK book (BL-16524). It's a fail-fast crash rather than a graceful no-op. Worth confirming whether any normal UI flow can request this endpoint with no current selection (e.g. transient states during collection switch / book close); if so, guard CurrentSelection/return an empty result.

[hatton]

[Claude Opus 4.8]

Question/possible bug: Language & Field-type submenus never appear on ordinary pages (bloom-customLayout gating)

The canvas-element context menu's language and fieldType rows are gated by ctx.isCustomPage, defined in src/BloomBrowserUI/bookEdit/toolbox/canvas/buildCanvasElementControlRegistryContext.ts:222 as:

isCustomPage: page?.classList.contains("bloom-customLayout") ?? false,

and enforced in canvasControlAvailabilityRules.ts (language.visible and fieldType.visible both require ctx.isCustomPage).

Observed at runtime: on real pages in a normal book, the page element is classed customPage bloom-combinedPage … — not bloom-customLayout. So even with a proper multilingual text canvas element selected (verified: khb/zh-CN/en), the context menu shows only Format text / Copy text / Paste text / Auto height / Duplicate / Delete — no "Language:" and no "Field:" submenu.

Note the language-name label on the context control (the langName div in CanvasElementContextControls.tsx:692) does render fine everywhere; it's specifically the language-switch submenu that's unreachable on these pages.

This may be intentional (perhaps bloom-customLayout is reserved for specific page types), but it means the language-submenu code path isn't exercised on typical pages. Flagging to confirm the class check is correct — customPage/bloom-combinedPage vs bloom-customLayout.

[hatton]

[Claude Opus 4.8]

Data oddity: stray z language editable in a CJK book

While inspecting a trilingual CJK book (Language1 khb, Language2 zh-CN, Language3 en), a translation-group text field on the page contained four .bloom-editable children, not three:

lang	visible
khb	yes
z	no (hidden)
en	yes
zh-CN	yes

The z tag looks like a truncated/invalid language code (possibly a mangled zh-CN), and its editable is hidden. This may just be pre-existing junk in this particular downloaded book rather than anything this PR introduced — but given it's a CJK/zh-CN book and the tag looks like a truncation of zh-CN, flagging it in case language-tag handling somewhere is producing/leaving a z editable. Worth a quick check that nothing in the keyboarding/language paths truncates zh-CN → z.

(Surfaced during the BL-16524 runtime check of the canvas-element context control.)