fix(engine): fall back to host fonts for scripts beyond CJK and emoji

On macOS only Hiragino and Apple Color Emoji were loaded, so Simplified
Chinese characters Japanese lacks, Hangul, Thai, Arabic, Hebrew, and
Devanagari rendered as boxes in a shot reported ok. The harness now
loads a fallback family per script on macOS, Linux, and Windows, after
the CJK and emoji ones, so text that rendered before renders unchanged.

The manual lists the fonts per host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: koji-1009

CHANGELOG.md

@@ -7,6 +7,7 @@ Host fallback fonts in text whose style keeps them out.
 * CJK and emoji in a `CupertinoAlertDialog` rendered as boxes in a shot reported `ok`: their text styles inherit nothing and name the Cupertino system font, so the host fonts added to the default text style and the themes never reached them. The host fonts are now appended to the text of every paragraph and text field before each layout.
 * Text in a style with its own `fontFamilyFallback`, such as google_fonts', now falls back to the host fonts too; Japanese in a Latin-only Google font rendered as boxes.
 * Text in a package font's style falls back as well.
+* Simplified Chinese, Hangul, Thai, Arabic, Hebrew, and Devanagari fall back to host fonts too; on macOS they rendered as boxes, and only Hiragino and Apple Color Emoji were loaded. Text that rendered before renders unchanged.
 
 ## 1.1.0
 

doc/manual.md

@@ -132,7 +132,7 @@ Images render at a device pixel ratio of 2.
 Elevation paints its shadow as on a device; `flutter_test` would draw a solid outline in its place.
 
 Fonts: every family in the project's `FontManifest.json` (pubspec `fonts:`, package fonts, MaterialIcons) plus Roboto from the Flutter SDK cache.
-The test engine has no system font fallback, so a glyph missing from the style's fonts would render as a box. As on a device, shutter falls back to the host's CJK and emoji fonts: Hiragino Sans W3/W6 and Apple Color Emoji on macOS, Noto Sans CJK and Noto Color Emoji on Linux, Yu Gothic and Segoe UI Emoji on Windows. They are appended as `fontFamilyFallback` to the ambient default text style, and to the text theme of every design library whose theme the shell provides (SDK or package); text whose glyphs exist in its own font renders unchanged.
+The test engine has no system font fallback, so a glyph missing from the style's fonts would render as a box. As on a device, shutter falls back to the host's fonts for CJK and emoji, then for the scripts those lack: Simplified Chinese, Hangul, Thai, Arabic, Hebrew, and Devanagari. On macOS they are Hiragino Sans W3/W6, Apple Color Emoji, Hiragino Sans GB, Apple SD Gothic Neo, Thonburi, SF Arabic, SF Hebrew, and Kohinoor Devanagari; on Linux, Noto Sans CJK, Noto Color Emoji, and Noto Sans Thai, Arabic, Hebrew, and Devanagari; on Windows, Yu Gothic, Segoe UI Emoji, Microsoft YaHei, Malgun Gothic, Leelawadee UI, Segoe UI, and Nirmala UI. A Han character takes the Japanese form when the CJK font has it. They are appended as `fontFamilyFallback` to the ambient default text style, and to the text theme of every design library whose theme the shell provides (SDK or package); text whose glyphs exist in its own font renders unchanged.
 Each frame, before layout, they are also appended to the text of every paragraph and text field, so text whose style keeps them out falls back too: a style that inherits nothing, such as a `CupertinoAlertDialog`'s, or one with its own `fontFamilyFallback`, such as google_fonts'.
 Cupertino text names the system font through the families `CupertinoSystemText` and `CupertinoSystemDisplay`, which the test engine does not resolve. On a macOS host they get SF Pro from `/System/Library/Fonts/`, as a macOS app does and as iOS draws; on other hosts, Roboto, the Android system font.
 Host fonts come from the machine that shoots, so compare runs made on the same machine.

lib/src/cli/manual_text.dart

@@ -135,7 +135,7 @@ Images render at a device pixel ratio of 2.
 Elevation paints its shadow as on a device; `flutter_test` would draw a solid outline in its place.
 
 Fonts: every family in the project's `FontManifest.json` (pubspec `fonts:`, package fonts, MaterialIcons) plus Roboto from the Flutter SDK cache.
-The test engine has no system font fallback, so a glyph missing from the style's fonts would render as a box. As on a device, shutter falls back to the host's CJK and emoji fonts: Hiragino Sans W3/W6 and Apple Color Emoji on macOS, Noto Sans CJK and Noto Color Emoji on Linux, Yu Gothic and Segoe UI Emoji on Windows. They are appended as `fontFamilyFallback` to the ambient default text style, and to the text theme of every design library whose theme the shell provides (SDK or package); text whose glyphs exist in its own font renders unchanged.
+The test engine has no system font fallback, so a glyph missing from the style's fonts would render as a box. As on a device, shutter falls back to the host's fonts for CJK and emoji, then for the scripts those lack: Simplified Chinese, Hangul, Thai, Arabic, Hebrew, and Devanagari. On macOS they are Hiragino Sans W3/W6, Apple Color Emoji, Hiragino Sans GB, Apple SD Gothic Neo, Thonburi, SF Arabic, SF Hebrew, and Kohinoor Devanagari; on Linux, Noto Sans CJK, Noto Color Emoji, and Noto Sans Thai, Arabic, Hebrew, and Devanagari; on Windows, Yu Gothic, Segoe UI Emoji, Microsoft YaHei, Malgun Gothic, Leelawadee UI, Segoe UI, and Nirmala UI. A Han character takes the Japanese form when the CJK font has it. They are appended as `fontFamilyFallback` to the ambient default text style, and to the text theme of every design library whose theme the shell provides (SDK or package); text whose glyphs exist in its own font renders unchanged.
 Each frame, before layout, they are also appended to the text of every paragraph and text field, so text whose style keeps them out falls back too: a style that inherits nothing, such as a `CupertinoAlertDialog`'s, or one with its own `fontFamilyFallback`, such as google_fonts'.
 Cupertino text names the system font through the families `CupertinoSystemText` and `CupertinoSystemDisplay`, which the test engine does not resolve. On a macOS host they get SF Pro from `/System/Library/Fonts/`, as a macOS app does and as iOS draws; on other hosts, Roboto, the Android system font.
 Host fonts come from the machine that shoots, so compare runs made on the same machine.

lib/src/engine/harness_text.dart

@@ -1104,10 +1104,25 @@ TextStyle _fallingBack(TextStyle style) {
   );
 }
 
-/// Host fonts covering CJK and emoji, by fallback family.
+/// Host fonts by fallback family, in fallback order: CJK, with Japanese
+/// forms for the Han characters they share, and emoji, then the scripts
+/// those lack. Each script is a family of its own, with one typeface per
+/// weight: the engine picks one typeface of a family by weight, not by
+/// glyph.
 Map<String, List<File>> _systemFallbackFonts() {
-  final cjk = <File>[];
-  final emoji = <File>[];
+  final families = <String, List<File>>{
+    for (final script in const [
+      'Cjk',
+      'Emoji',
+      'Hans',
+      'Hangul',
+      'Thai',
+      'Arabic',
+      'Hebrew',
+      'Devanagari',
+    ])
+      'ShutterFallback$script': <File>[],
+  };
   List<File> files(String dir) {
     final directory = Directory(dir);
     if (!directory.existsSync()) return const [];
@@ -1123,19 +1138,38 @@ Map<String, List<File>> _systemFallbackFonts() {
 
   // Exact paths rather than directory listings: macOS returns
   // decomposed (NFD) Japanese file names, which never equal a literal.
-  List<File> existing(List<String> paths) => [
-    for (final path in paths)
-      if (File(path).existsSync()) File(path),
-  ];
+  void existing(String dir, Map<String, List<String>> names) {
+    for (final MapEntry(key: script, value: files) in names.entries) {
+      for (final name in files) {
+        final file = File('$dir${Platform.pathSeparator}$name');
+        if (file.existsSync()) families['ShutterFallback$script']!.add(file);
+      }
+    }
+  }
+
   if (Platform.isMacOS) {
-    cjk.addAll(
-      existing([
-        '/System/Library/Fonts/ヒラギノ角ゴシック W3.ttc',
-        '/System/Library/Fonts/ヒラギノ角ゴシック W6.ttc',
-      ]),
-    );
-    emoji.addAll(existing(['/System/Library/Fonts/Apple Color Emoji.ttc']));
+    existing('/System/Library/Fonts', const {
+      'Cjk': ['ヒラギノ角ゴシック W3.ttc', 'ヒラギノ角ゴシック W6.ttc'],
+      'Emoji': ['Apple Color Emoji.ttc'],
+      'Hans': ['Hiragino Sans GB.ttc'],
+      'Hangul': ['AppleSDGothicNeo.ttc'],
+      'Thai': ['ThonburiUI.ttc'],
+      'Arabic': ['SFArabic.ttf'],
+      'Hebrew': ['SFHebrew.ttf'],
+      'Devanagari': ['Kohinoor.ttc'],
+    });
   } else if (Platform.isLinux) {
+    // Noto Sans CJK holds every CJK script in each of its faces.
+    const noto = {
+      'NotoSansThai-Regular.ttf': 'Thai',
+      'NotoSansThai-Bold.ttf': 'Thai',
+      'NotoSansArabic-Regular.ttf': 'Arabic',
+      'NotoSansArabic-Bold.ttf': 'Arabic',
+      'NotoSansHebrew-Regular.ttf': 'Hebrew',
+      'NotoSansHebrew-Bold.ttf': 'Hebrew',
+      'NotoSansDevanagari-Regular.ttf': 'Devanagari',
+      'NotoSansDevanagari-Bold.ttf': 'Devanagari',
+    };
     final home = Platform.environment['HOME'];
     for (final dir in [
       '/usr/share/fonts',
@@ -1145,22 +1179,31 @@ Map<String, List<File>> _systemFallbackFonts() {
     ]) {
       for (final file in files(dir)) {
         final n = file.path.split(Platform.pathSeparator).last;
-        if ((n.startsWith('NotoSansCJK') || n.startsWith('NotoSansJP')) &&
-            (n.contains('Regular') || n.contains('Bold'))) {
-          cjk.add(file);
-        } else if (n == 'NotoColorEmoji.ttf') {
-          emoji.add(file);
-        }
+        final script = switch (n) {
+          _ when (n.startsWith('NotoSansCJK') || n.startsWith('NotoSansJP')) &&
+              (n.contains('Regular') || n.contains('Bold')) =>
+            'Cjk',
+          'NotoColorEmoji.ttf' => 'Emoji',
+          _ => noto[n],
+        };
+        if (script != null) families['ShutterFallback$script']!.add(file);
       }
     }
   } else if (Platform.isWindows) {
-    final fonts = '${Platform.environment['WINDIR'] ?? r'C:\Windows'}\\Fonts';
-    cjk.addAll(existing(['$fonts\\YuGothR.ttc', '$fonts\\YuGothB.ttc']));
-    emoji.addAll(existing(['$fonts\\seguiemj.ttf']));
+    // Segoe UI holds Hebrew as well as Arabic.
+    existing('${Platform.environment['WINDIR'] ?? r'C:\Windows'}\\Fonts', const {
+      'Cjk': ['YuGothR.ttc', 'YuGothB.ttc'],
+      'Emoji': ['seguiemj.ttf'],
+      'Hans': ['Msyh.ttc', 'Msyhbd.ttc'],
+      'Hangul': ['Malgun.ttf', 'Malgunbd.ttf'],
+      'Thai': ['Leelawui.ttf', 'Leelauib.ttf'],
+      'Arabic': ['Segoeui.ttf', 'Segoeuib.ttf'],
+      'Devanagari': ['Nirmala.ttf', 'Nirmalab.ttf'],
+    });
   }
   return {
-    if (cjk.isNotEmpty) 'ShutterFallbackCjk': cjk,
-    if (emoji.isNotEmpty) 'ShutterFallbackEmoji': emoji,
+    for (final MapEntry(key: family, value: files) in families.entries)
+      if (files.isNotEmpty) family: files,
   };
 }
 

test/e2e/shell_test.dart

@@ -4,6 +4,7 @@ library;
 import 'dart:io';
 import 'dart:math';
 
+import 'package:crypto/crypto.dart';
 import 'package:image/image.dart' as img;
 import 'package:path/path.dart' as p;
 import 'package:shutter/src/run/manifest.dart';
@@ -259,6 +260,47 @@ Widget shown() => Builder(
     },
   );
 
+  test(
+    'scripts beyond CJK fall back to host fonts',
+    () async {
+      final root = await exampleCopy();
+      // The same letters in two orders: boxes draw them alike, glyphs
+      // differently. Han characters only Simplified Chinese has.
+      const scripts = {
+        'Hans': ('这们说', '说这们'),
+        'Hangul': ('한국어', '어한국'),
+        'Thai': ('กขค', 'คกข'),
+        'Arabic': ('عرب', 'برع'),
+        'Hebrew': ('אבג', 'גאב'),
+        'Devanagari': ('कखग', 'गकख'),
+      };
+      writeFiles(root, {
+        'lib/preview/scripts_preview.dart': [
+          "import 'package:flutter/widget_previews.dart';",
+          "import 'package:flutter/widgets.dart';",
+          for (final MapEntry(key: script, value: (a, b)) in scripts.entries)
+            for (final (i, text) in [(1, a), (2, b)]) ...[
+              "@Preview(name: '$script $i', size: Size(200, 40))",
+              "Widget ${script.toLowerCase()}$i() => const Text('$text');",
+            ],
+        ].join('\n'),
+      });
+      final (run, shots) = await shootIn(root, [
+        'lib/preview/scripts_preview.dart',
+      ]);
+      Digest png(String name) => sha256.convert(
+        File(p.join(run, shots[name]!.png!)).readAsBytesSync(),
+      );
+      final boxes = [
+        for (final script in scripts.keys)
+          if (png('$script 1') == png('$script 2')) script,
+      ];
+      expect(boxes, isEmpty, reason: 'rendered as boxes');
+    },
+    // The CI host has emoji fonts only.
+    skip: Platform.isMacOS ? false : 'needs the macOS host fonts',
+  );
+
   test('a project on material_ui gets a material_ui default shell', () async {
     final root = await exampleCopy();
     File(p.join(root, 'lib', 'preview', 'shell.dart')).deleteSync();