fix(ios): load host page, keyboards through a consistent WKURLSchemeHandler by jahorton · Pull Request #16136 · keymanapp/keyman

jahorton · 2026-06-24T21:03:18Z

These changes bypass any need to modify KMW keyboard loading (say, via .fetch), instead forcing all engine files and resources to load via the new scheme/protocol in order to accomplish its goal.

Alternate approaches considered:

monkeypatching fetches on file:// protocol calls to ping Swift for a file load, then pass the results back via JS call that resolves the associated fetch Promise.
- Would require fewer changes, but would require that one point of monkeypatching.

Build-bot: skip release:ios,web

User Testing

TEST_IOS:

Install Keyman for iPhone and iPad from this PR
Verify that a keyboard properly shows
Verify that the predictive-text banner shows suggestions (use a keyboard/language with an associated lexical model)

TEST_IOS_CAMEROON:

Install Keyman for iPhone and iPad from this PR
Download and install the sil_cameroon_azerty keyboard
Verify that the keyboard's custom CSS displays properly.
Verify that the keyboard's display font (for the main keys) differs from that of sil_euro_latin.

TEST_FIRSTVOICES:

Install FirstVoices App from this PR
Verify that a keyboard properly shows

TEST_WEB:

Open KeymanWeb test page, navigate to any test
Select a keyboard and verify that it displays the OSK and that the console window doesn't show errors

TEST_WEB_KBD_DOCS:

Open KeymanWeb test page titled "Tests keyboard documentation rendering"
Verify that all keyboard renders load correctly and lack any obvious visual errors.

keymanapp-test-bot · 2026-06-24T21:03:23Z

User Test Results

Test specification and instructions

✅ TEST_IOS (PASSED) (notes)
✅ TEST_IOS_CAMEROON (PASSED) (notes)
✅ TEST_FIRSTVOICES (PASSED)
✅ TEST_WEB (PASSED) (notes)
✅ TEST_WEB_KBD_DOCS (PASSED): ): (notes)

Test Artifacts

iOS
Web
- KeymanWeb Test Home

mcdurdin

I like where this is going, some feedback and thoughts on how to tighten it up.

mcdurdin · 2026-06-25T04:36:13Z

    // Absolute
-    if((p.replace(/^(http)s?:.*/,'$1') == 'http') || (p.replace(/^(file):.*/,'$1') == 'file')) {
-      return p;
+    if(p.indexOf(this.protocol) == 0) {


Suggested change

if(p.indexOf(this.protocol) == 0) {

if(p.startsWith(this.protocol)) {

But note that http vs https was catered for here previously whereas this change does not allow for that (so http <--> https will no longer work). This is probably not a big deal, but something to be aware of.

I am actually more worried about this one now: if a user has a local website running http but sources KeymanWeb from https://s.keyman.com, will it break?

My local testing on Mac is done via http-server, meaning the local test site is based on http. It still uses https://api.keyman.com and https://s.keyman.com with zero issue.

mcdurdin · 2026-06-25T04:42:03Z

  }

  updateFromOptions(pathSpec: Required<PathOptionSpec>) {
    const _rootPath = this.sourcePath.replace(/(https?:\/\/)([^\/]*)(.*)/,'$1$2/');


Will this also need fixup?

Not exactly sure what it's doing, and I didn't need to change it, so I decided to leave this be.

I wonder if that will cause subtle issues somewhere given this only works with http[s]: and not with keyman-engine:. It might be good to understand why this is needed.

mcdurdin · 2026-06-25T04:42:06Z


  // Local function to convert relative to absolute URLs
  // with respect to the source path, server root and protocol
  fixPath(p: string) {


Could this whole function be replaced with new URL(p, this.sourcePath)?

I'd want to test that out more thoroughly as its own PR, rather than rolling it in here.

mcdurdin · 2026-06-25T05:13:56Z

+      // +1:  include the ':' that likely exists
+      pathComponent = String(components.path.dropFirst(KeymanWebViewController.SCHEME.count + 1))
+    }
+


I'm confused about this piece of code. Surely pathComponent should never include keyman-engine:? That would be components.scheme?

Also, I think this would be a good place to collapse repeated slashes, both at start of string and beyond, because repeated slashes when building paths is a common bug and I think we can be resilient to it without real penalty.

That also removes the need to do that work in pathConfiguration.ts.

pathComponent = components.path.replacingOccurrences(of: "/+", with: "/", options: .regularExpression) if pathComponent.hasPrefix("/") { pathComponent = pathComponent.dropFirst() }

Something like that?

This was an earlier attempt to work around issues in which URLs like the following appeared: keyman-engine:/keyman-engine:/kmwosk.css

It didn't work, which led to resolving things in Web engine code - the changes to pathConfiguration.ts, oskView.ts, and visualKeyboard.ts.

Will clean up now.

That also removes the need to do that work in pathConfiguration.ts.

pathComponent = components.path.replacingOccurrences(of: "/+", with: "/", options: .regularExpression) if pathComponent.hasPrefix("/") { pathComponent = pathComponent.dropFirst() }

... about that. If there are repeated leading slashes, URLComponents will consider the 'path' as the host, not a path! For most of our resources, this then results in a nil path, which is very much something we don't want. Some of the changes seen in pathConfiguration.ts were made b/c they're the easiest workaround... or were at the time.

... and fortunately, the fixes in OSK code resolved the cases that were causing this, so we can still knock the pathConfiguration.ts double-slash handling out!

mcdurdin · 2026-06-25T05:16:13Z

One more thought; can we base this on #16132 so that we are looking at a consolidated fix for both platforms?

jahorton · 2026-06-25T15:46:55Z

One more thought; can we base this on #16132 so that we are looking at a consolidated fix for both platforms?

Work is still ongoing there, and there's been at least one force-push to that branch since the quoted comment was posted. I'd have to re-force-push this branch every time a force-push happens there.

Pretty much just what the title says; it's been silently missing this whole time. This doesn't fix iOS keyboard's display by itself, but it is a prerequisite for the full solution offered by #16136. Build-bot: skip build:ios Test-bot: skip

…andler This bypasses any need to modify KMW keyboard loading (say, via .fetch), though it does require a number of collateral changes to be made in order for CORS, etc to be satisfied. Build-bot: skip build:ios

Pretty much just what the title says; it's been silently missing this whole time. This doesn't fix iOS keyboard's display by itself, but it is a prerequisite for the full solution offered by #16136. Build-bot: skip build:ios Test-bot: skip

Meng-Heng · 2026-06-29T06:55:12Z

Test Results

TEST_WEB (PASSED):

Navigate to KeymanWeb Test Page
Go to View Keymanweb website-oriented manual test pages -> Test unminified Keymanweb (unminified)
Verified: Keyboards render fine without any visual nor console errors
Verified: The keyboards switch and display correctly
Verified: Typing on the selected keyboard work as expected.
Go to View Keymanweb website-oriented manual test pages -> Prediction - robust testing (prediction-mtnt)
Verified: Keyboards and Predictive text are working as expected
Verified: Typing and switching keyboards are working perfectly
Verified: Throughout the test period, the console does not have any error messages.

TEST_WEB_KBD_DOCS (PASSED):

Continue with KeymanWeb Test Page
Open KeymanWeb test page titled "Tests keyboard documentation rendering"
Verified: all keyboard renders load beautifully
Verified: there are no error visuals.

Note

For the TEST_WEB_KBD_DOCS test, the console has the following error https://build.palaso.org/repository/download/Keymanweb_TestPullRequests/630677:id/build/publish/debug/keymanweb-osk.ttf after the OSK loaded.

Meng-Heng · 2026-06-29T07:11:28Z

Test Results

TEST_IOS (PASSED):

Download and Install Keyman for iPhone and iPad v19.0.248-alpha-test-16136
Verified: The EuroLatin (SIL) keyboard shows up with the predictive text
Verified: Typing and using predictive text work as expected

TEST_IOS_CAMEROON (PASSED):

Continue from the test above without restarting the app
Go to Settings -> Install Keyboard -> Download the Cameroon Azerty keyboard
Verified: The CSS displays accordingly with its unique font.

Note

The App had been stuck at loading when launched without any error messages. The app was dismissed and relaunched to get through the loading screen.

jahorton · 2026-06-29T14:53:17Z

Note

For the TEST_WEB_KBD_DOCS test, the console has the following error https://build.palaso.org/repository/download/Keymanweb_TestPullRequests/630677:id/build/publish/debug/keymanweb-osk.ttf after the OSK loaded.

Thanks for catching that! Could you retest and verify that these errors no longer occur?

@keyman-test-bot retest TEST_WEB_KBD_DOCS

mcdurdin · 2026-06-29T15:03:57Z

+        browser?: DeviceSpec.Browser
      } = {};

    // Device emulation for target documentation.
    device.formFactor = formFactor;
    if (formFactor != 'desktop') {
      device.OS = DeviceSpec.OperatingSystem.iOS;
      device.touchable = true;
+      device.browser = DeviceSpec.Browser.Safari;
    } else {
      device.OS = DeviceSpec.OperatingSystem.Windows;
      device.touchable = false;
+      device.browser = DeviceSpec.Browser.Chrome;


Why these changes? device.browser doesn't appear to be used anywhere else in the PR?

See the changes at lines 1404 - 1408 - they're needed to complete the requirements of the DeviceSpec type needed for the .hostDevice field of getResourcePath's parameter.

Alternatively, we could mock it out with null, but that could become prone to breakage. Or we could rework the getResourcePath method to use just pathConfig.

OK, makes sense, long term would be good if getResourcePath didn't require device info

Co-authored-by: Marc Durdin <marc@durdin.net>

We don't actually pass JSON through our scheme handler yet, but just in case... we ensure we detect JSON's MIME type and annotate appropriately

Meng-Heng · 2026-06-30T06:02:43Z

TEST_WEB_KBD_DOCS (PASSED):

Open KeymanWeb Test Page
Navigate to KeymanWeb test page titled "Tests keyboard documentation rendering"
Verified: all keyboard renders beautifully
Verified: there are no error visuals
Verified: no error in console.

mcdurdin · 2026-06-30T08:02:07Z

We need a user test for FirstVoices Keyboards also

jahorton · 2026-06-30T14:24:02Z

We need a user test for FirstVoices Keyboards also

Added. Also made sure it at least works on my local build.

Meng-Heng · 2026-07-01T04:25:58Z

I can't seem to find the build for FirstVoices. Please help check

mcdurdin · 2026-07-01T04:36:55Z

I can't seem to find the build for FirstVoices. Please help check

The iOS build is currently disabled due to updates that the FirstVoices team need to make on App Store Connect.

Given @jahorton verified that a local build works, we'll move forward with that for now.

TEST_FIRSTVOICES PASS

keyman-server · 2026-07-01T18:01:19Z

Changes in this pull request will be available for download in Keyman version 19.0.250-alpha

ermshiperete · 2026-07-02T08:54:12Z

Fixes iOS part of #16096

github-project-automation Bot added this to Keyman Jun 24, 2026

github-project-automation Bot moved this to Todo in Keyman Jun 24, 2026

keymanapp-test-bot Bot added the user-test-missing User tests have not yet been defined for the PR label Jun 24, 2026

keymanapp-test-bot Bot added this to the A19S32 milestone Jun 24, 2026

github-actions Bot added web/ ios/ ios/engine/ fix labels Jun 24, 2026

mcdurdin reviewed Jun 25, 2026

View reviewed changes

jahorton force-pushed the fix/ios/load-via-scheme-handler branch from 2e9568e to b9a3c11 Compare June 25, 2026 15:47

keymanapp-test-bot Bot added has-user-test user-test-required User tests have not been completed and removed user-test-missing User tests have not yet been defined for the PR labels Jun 25, 2026

jahorton force-pushed the fix/ios/load-via-scheme-handler branch from b9a3c11 to 1f99b2d Compare June 25, 2026 16:07

jahorton mentioned this pull request Jun 25, 2026

fix(ios): bundle in KMW's globe-hint.css #16142

Merged

jahorton changed the base branch from master to fix/ios/bundle-globe-hint June 25, 2026 18:23

jahorton force-pushed the fix/ios/load-via-scheme-handler branch from 1f99b2d to 08c2f25 Compare June 25, 2026 18:23

fix(ios): load host page, keyboards through a consistent WKURLSchemeH…

b3ee271

…andler This bypasses any need to modify KMW keyboard loading (say, via .fetch), though it does require a number of collateral changes to be made in order for CORS, etc to be satisfied. Build-bot: skip build:ios

jahorton force-pushed the fix/ios/bundle-globe-hint branch from df26dc4 to 13e154f Compare June 26, 2026 19:38

jahorton force-pushed the fix/ios/load-via-scheme-handler branch from 08c2f25 to b3ee271 Compare June 26, 2026 19:39

jahorton requested review from ermshiperete and sgschantz June 26, 2026 19:39

jahorton marked this pull request as ready for review June 26, 2026 19:39

keymanapp-test-bot Bot removed the user-test-required User tests have not been completed label Jun 29, 2026

fix(web): set proper font path for doc-keyboards

eea463b

mcdurdin reviewed Jun 29, 2026

View reviewed changes

jahorton and others added 2 commits June 29, 2026 22:21

docs(ios): change file header date format

fa435cb

Co-authored-by: Marc Durdin <marc@durdin.net>

change(ios): pre-emptively denote utf-8 encoding for JSON

700380d

We don't actually pass JSON through our scheme handler yet, but just in case... we ensure we detect JSON's MIME type and annotate appropriately

mcdurdin mentioned this pull request Jun 30, 2026

bug(web): error displayed when typing with korean_rr keyboard in Keyman for iOS or Keyman for Android #16144

Closed

mcdurdin approved these changes Jun 30, 2026

View reviewed changes

keymanapp-test-bot Bot added the user-test-required User tests have not been completed label Jun 30, 2026

keymanapp-test-bot Bot removed the user-test-required User tests have not been completed label Jul 1, 2026

Base automatically changed from fix/ios/bundle-globe-hint to master July 1, 2026 14:56

jahorton merged commit 824925a into master Jul 1, 2026
10 checks passed

github-project-automation Bot moved this from Todo to Done in Keyman Jul 1, 2026

jahorton deleted the fix/ios/load-via-scheme-handler branch July 1, 2026 14:57

ermshiperete linked an issue Jul 2, 2026 that may be closed by this pull request

bug(web): blank keyboard after installing Keyman for Android or Keyman for iOS 19.0.242 or later #16096

Closed

ermshiperete mentioned this pull request Jul 2, 2026

bug(web): blank keyboard after installing Keyman for Android or Keyman for iOS 19.0.242 or later #16096

Closed

mcdurdin mentioned this pull request Jul 6, 2026

refactor(web): remove unnecessary getResourcePath dependency on DeviceSpec #16206

Open

	if(p.indexOf(this.protocol) == 0) {
	if(p.startsWith(this.protocol)) {

Uh oh!

Uh oh!

Conversation

jahorton commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Testing

Uh oh!

keymanapp-test-bot Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Test Artifacts

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jahorton Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcdurdin commented Jun 25, 2026

Uh oh!

jahorton commented Jun 25, 2026

Uh oh!

Meng-Heng commented Jun 29, 2026

Test Results

Uh oh!

Meng-Heng commented Jun 29, 2026

Test Results

Uh oh!

jahorton commented Jun 29, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Meng-Heng commented Jun 30, 2026

Uh oh!

mcdurdin commented Jun 30, 2026

Uh oh!

jahorton commented Jun 30, 2026

Uh oh!

Meng-Heng commented Jul 1, 2026

Uh oh!

mcdurdin commented Jul 1, 2026

Uh oh!

Uh oh!

keyman-server commented Jul 1, 2026

Uh oh!

ermshiperete commented Jul 2, 2026

Uh oh!

jahorton commented Jun 24, 2026 •

edited

Loading

keymanapp-test-bot Bot commented Jun 24, 2026 •

edited

Loading

jahorton Jun 25, 2026 •

edited

Loading