Map native:* font handles to installed iOS-family fonts in JavaSE simulator and add tests/docs

[liannacasper]

Motivation

• Improve fidelity of native:* font handling in the JavaSE simulator by selecting a real installed iOS-family font when running with an iOS skin.
• Avoid attempting to distribute or hard-code Apple fonts and instead detect and prefer locally installed San Francisco / Helvetica Neue families when available.
• Clarify simulator behavior and licensing implications in the docs so users know how to obtain exact iOS fonts if desired.

Description

• Added a mapping IOS_NATIVE_FONT_CANDIDATES of native:* handles to ordered iOS-family font family name candidates and implemented detection of installed font families via getAvailableFontNamesLowercase().
• Added helper utilities findFirstInstalledFontCandidate, nativeFontNameForIOS, and test helpers setAvailableFontNamesLowercaseForTest/clearAvailableFontNamesLowercaseForTest to control font detection in tests.
• Modified nativeFontName and loadTrueTypeFont to return and use a real installed font on iOS simulator runs (and otherwise fall back to existing behavior), preserving cross-platform fallbacks.
• Updated documentation to explain that Codename One does not bundle Apple iOS fonts, that the simulator prefers San Francisco/SF Pro (or Helvetica Neue) when installed, and added a FAQ entry with setup guidance for macOS/Windows/Linux.

Testing

• Added maven/javase JUnit tests in JavaSEPortFontMappingTest covering findFirstInstalledFontCandidate, nativeFontNameForIOS behavior and loadTrueTypeFont fallbacks, and ran them under the JavaSE test profile; all tests passed.
• The new tests exercised the installed-font detection logic and the simulator-path in loadTrueTypeFont and verified both positive and fallback flows.

---

Codex Task

[github-actions]

Developer Guide build artifacts are available for download from this workflow run:

• Developer Guide HTML package
• Developer Guide PDF
• AsciiDoc linter report
• Vale report
• Unused image report

Developer Guide quality checks:

• AsciiDoc linter: 1 issue(s) flagged (1 errors) (exit code 1) (report)
• Vale: 18579 alert(s) (2700 errors, 6345 warnings, 9534 suggestions) (exit code 1) (report)
• Image references: 33 unused image(s) found (report)

Unused image preview:

• img/uwp-app-manager-apps.png
• img/uwp-certificate-generator.png
• img/uwp-cn1settings-debug-desktop-selected.png
• img/uwp-cn1settings-disk-icon.png
• img/uwp-cn1settings-uwp.png
• img/uwp-cn1settings-windows-settings-menu-item.png
• img/uwp-dashboard-download-appxbundle.png
• img/uwp-extract-zip-file.png
• img/uwp-mobile-recently-added.png
• img/uwp-mobile-settings-developer-mode.png
• ... and 23 more

[shai-almog]

Compared 35 screenshots: 35 matched.

Native Android coverage

• 📊 Line coverage: 7.74% (3954/51097 lines covered) [HTML preview] (artifact android-coverage-report, jacocoAndroidReport/html/index.html)
  • Other counters: instruction 6.11% (19607/321133), branch 2.88% (896/31161), complexity 3.61% (1077/29819), method 6.37% (886/13907), class 10.56% (195/1847)
  • Lowest covered classes
    • kotlin.collections.kotlin.collections.ArraysKt___ArraysKt – 0.00% (0/6327 lines covered)
    • kotlin.collections.unsigned.kotlin.collections.unsigned.UArraysKt___UArraysKt – 0.00% (0/2384 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.ClassReader – 0.00% (0/1519 lines covered)
    • kotlin.collections.kotlin.collections.CollectionsKt___CollectionsKt – 0.00% (0/1148 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.MethodWriter – 0.00% (0/923 lines covered)
    • kotlin.sequences.kotlin.sequences.SequencesKt___SequencesKt – 0.00% (0/712 lines covered)
    • kotlin.text.kotlin.text.StringsKt___StringsKt – 0.00% (0/623 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.Frame – 0.00% (0/564 lines covered)
    • kotlin.collections.kotlin.collections.ArraysKt___ArraysJvmKt – 0.00% (0/495 lines covered)
    • kotlinx.coroutines.kotlinx.coroutines.JobSupport – 0.00% (0/423 lines covered)

✅ Native Android screenshot tests passed.

Native Android coverage

• 📊 Line coverage: 7.74% (3954/51097 lines covered) [HTML preview] (artifact android-coverage-report, jacocoAndroidReport/html/index.html)
  • Other counters: instruction 6.11% (19607/321133), branch 2.88% (896/31161), complexity 3.61% (1077/29819), method 6.37% (886/13907), class 10.56% (195/1847)
  • Lowest covered classes
    • kotlin.collections.kotlin.collections.ArraysKt___ArraysKt – 0.00% (0/6327 lines covered)
    • kotlin.collections.unsigned.kotlin.collections.unsigned.UArraysKt___UArraysKt – 0.00% (0/2384 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.ClassReader – 0.00% (0/1519 lines covered)
    • kotlin.collections.kotlin.collections.CollectionsKt___CollectionsKt – 0.00% (0/1148 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.MethodWriter – 0.00% (0/923 lines covered)
    • kotlin.sequences.kotlin.sequences.SequencesKt___SequencesKt – 0.00% (0/712 lines covered)
    • kotlin.text.kotlin.text.StringsKt___StringsKt – 0.00% (0/623 lines covered)
    • org.jacoco.agent.rt.internal_b6258fc.asm.org.jacoco.agent.rt.internal_b6258fc.asm.Frame – 0.00% (0/564 lines covered)
    • kotlin.collections.kotlin.collections.ArraysKt___ArraysJvmKt – 0.00% (0/495 lines covered)
    • kotlinx.coroutines.kotlinx.coroutines.JobSupport – 0.00% (0/423 lines covered)

[github-actions]

Cloudflare Preview

• URL: https://pr-4708-website-preview.codenameone.pages.dev
• Branch: pr-4708-website-preview

[github-actions]

✅ Continuous Quality Report

Test & Coverage

• ✅ Tests: 2363 total, 0 failed, 0 skipped
• 📊 Line coverage: 53.37% [HTML preview] [Download]
  • Lowest covered classes
    • com.codename1.ui.Display$EdtException – 0.00%
    • com.codename1.ui.plaf.CSSBorder$LinearGradient – 0.00%
    • com.codename1.util.EasyThread$InQueueRunnable – 0.00%
    • com.codename1.components.FloatingActionButton$ReleaseActionListener – 0.00%
    • com.codename1.io.Oauth2$ShowAuthenticationActionListener – 0.00%
    • com.codename1.io.Oauth2$RefreshTokenActionListener – 0.00%
    • com.codename1.util.EasyThread$RunAndWaitRunnable – 0.00%
    • com.codename1.components.ToastBar$FlushAnimationCallback – 0.00%
    • com.codename1.ui.plaf.CSSBorder$ColorStop – 0.00%
    • com.codename1.ui.ElevationComparator – 0.00%

Static Analysis

• SpotBugs [HTML preview] [Download]
  • ❌ ByteCodeTranslator: 109 findings (High: 2, Normal: 80, Low: 27)
    • Top findings
      • High: com/codename1/tools/translator/BytecodeMethod.java:559 – Method com.codename1.tools.translator.BytecodeMethod.findWritableFields(Set) seems to be useless (rule: UC_USELESS_VOID_METHOD)
      • High: com/codename1/tools/translator/bytecodes/TryCatch.java:91 – Write to static field com.codename1.tools.translator.bytecodes.TryCatch.hasTryCatch from instance method com.codename1.tools.translator.bytecodes.TryCatch.appendInstruction(StringBuilder, List) (rule: ST_WRITE_TO_STATIC_FROM_INSTANCE_METHOD)
      • Normal: com/codename1/tools/translator/ByteCodeClass.java:1802 – com.codename1.tools.translator.ByteCodeClass.getBaseClassObject() may expose internal representation by returning ByteCodeClass.baseClassObject (rule: EI_EXPOSE_REP)
      • …and 106 more
  • ❌ android: 413 findings (High: 24, Normal: 196, Low: 193)
    • Top findings
      • High: CodenameOne/src/com/codename1/impl/CodenameOneThread.java:48 – com.codename1.impl.CodenameOneThread.STACK_FRAME_SIZE isn't final but should be (rule: MS_SHOULD_BE_FINAL)
      • High: com/codename1/impl/android/AndroidImplementation.java:1085 – Write to static field com.codename1.impl.android.AndroidImplementation.context from instance method com.codename1.impl.android.AndroidImplementation.setContext(Context) (rule: ST_WRITE_TO_STATIC_FROM_INSTANCE_METHOD)
      • High: com/codename1/impl/android/AndroidImplementation.java:1286 – com.codename1.impl.android.AndroidImplementation.isDarkMode() has Boolean return type and returns explicit null (rule: NP_BOOLEAN_RETURN_NULL)
      • …and 410 more
  • ❌ codenameone-maven-plugin: 488 findings (High: 1, Normal: 315, Low: 172)
    • Top findings
      • High: com/codename1/maven/AbstractCN1Mojo.java:807 – com.codename1.maven.AbstractCN1Mojo.OS isn't final but should be (rule: MS_SHOULD_BE_FINAL)
      • Normal: com/codename1/builders/AndroidGradleBuilder.java:1018 – Dead store to googleServicesJson in com.codename1.builders.AndroidGradleBuilder.build(File, BuildRequest) (rule: DLS_DEAD_LOCAL_STORE)
      • Normal: com/codename1/builders/AndroidGradleBuilder.java:1043 – Possible null pointer dereference in com.codename1.builders.AndroidGradleBuilder.build(File, BuildRequest) due to return value of called method (rule: NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE)
      • …and 485 more
  • ❌ core-unittests: 1 findings (Normal: 1)
    • Top findings
      • Normal: CodenameOne/src/com/codename1/ui/util/MutableResource.java:239 – com.codename1.ui.util.MutableResource.saveL10N(DataOutputStream, Hashtable) makes inefficient use of keySet iterator instead of entrySet iterator (rule: WMI_WRONG_MAP_ITERATOR)
  • ❌ ios: 125 findings (High: 4, Normal: 75, Low: 46)
    • Top findings
      • High: com/codename1/impl/ios/IOSImplementation.java:1228 – com.codename1.impl.ios.IOSImplementation.isDarkMode() has Boolean return type and returns explicit null (rule: NP_BOOLEAN_RETURN_NULL)
      • High: com/codename1/impl/ios/IOSImplementation.java:128 – com.codename1.impl.ios.IOSImplementation.nativeInstance isn't final but should be (rule: MS_SHOULD_BE_FINAL)
      • High: com/codename1/impl/ios/IOSImplementation.java:214 – Write to static field com.codename1.impl.ios.IOSImplementation.instance from instance method com.codename1.impl.ios.IOSImplementation.init(Object) (rule: ST_WRITE_TO_STATIC_FROM_INSTANCE_METHOD)
      • …and 122 more
• ✅ PMD: 0 findings (no issues) [Report archive]
• ✅ Checkstyle: 0 findings (no issues) [Report archive]

Generated automatically by the PR CI workflow.

[shai-almog]

Compared 35 screenshots: 35 matched.
✅ Native iOS screenshot tests passed.

Benchmark Results

• VM Translation Time: 0 seconds
• Compilation Time: 195 seconds

Detailed Performance Metrics

Metric	Duration
Simulator Boot	1000 ms
Simulator Boot (Run)	2000 ms
App Install	3000 ms
App Launch	10000 ms
Test Execution	168000 ms