Fail the CSS compile on @font-face rules the runtime can't honor

docs/developer-guide/css.asciidoc

@@ -593,7 +593,7 @@ If you want to use a font other than the built-in fonts, you'll need to define t
 include::../demos/common/src/main/css/guide-snippets-theme.css[tag=css-css-028,indent=0]
 ----
 
-IMPORTANT: Only TrueType (`.ttf`) files are supported. OpenType (`.otf`) files compile without an error, but the runtime rejects any font file whose name doesn't end in `.ttf`, and the iOS build registers only `.ttf` files with the operating system. Convert an OpenType font to TrueType before referencing it.
+IMPORTANT: Only TrueType (`.ttf`) files are supported. The runtime loads a font by a file name ending in `.ttf` and the iOS build registers only those files with the operating system, so the CSS compiler fails the build on anything else rather than letting it reach the device. Convert an OpenType (`.otf`) font to TrueType before referencing it. The compiler also reads each font at build time, so a file it can't parse, or one with no PostScript name, fails the build too -- iOS resolves fonts by their PostScript name, so a font without one would render everywhere except on an iOS device.
 
 Then you'll be able to reference the font using the specified `font-family` in any CSS element. For example:
 
@@ -611,6 +611,8 @@ A relative `src` URL is resolved against the directory that holds the CSS file.
 include::../demos/common/src/main/css/guide-snippets-theme.css[tag=css-css-044,indent=0]
 ----
 
+The font does have to live somewhere under that directory, because only that directory is copied into the build. A font reached through `../`, or one that doesn't exist, fails the build rather than producing an app whose text falls back to the system font. Two `@font-face` rules naming different files that share a file name also fail, since fonts are deployed by file name alone and one would overwrite the other. Pointing two families at the same file is fine.
+
 ===== Family names, weights and styles
 
 A `font-family` name that contains spaces must be quoted, both in the `@font-face` rule and wherever you reference it. An unquoted name is parsed as a list of separate identifiers, so `font-family: GuideDemoFont Bold` registers the family as `GuideDemoFont` and collides with your regular weight.

maven/css-compiler/src/main/java/com/codename1/designer/css/CSSTheme.java

@@ -2115,7 +2115,199 @@ private void emitColorBinding(EditableResources res, String themeName, String th
         res.setThemeProperty(themeName, "@cn1-bind:" + themeKey, varName);
     }
 
+    /// Fails the compile for `@font-face` rules the runtime cannot honor.
+    ///
+    /// Without this the errors are invisible until the app runs, because the
+    /// compiler and the device disagree about what a "true type font" is. The
+    /// compiler loads fonts through `java.awt.Font.createFont(TRUETYPE_FONT, ...)`,
+    /// which also parses OpenType/CFF, so an `.otf` compiles clean and then
+    /// `Font.createTrueTypeFont` throws on device because the name doesn't end
+    /// in `.ttf` -- and the iOS build never registered it with the OS anyway.
+    /// A font outside the CSS directory fails the same way: merge mode syncs
+    /// only that directory, so the reference resolves on the authoring machine
+    /// and breaks in a real build.
+    ///
+    /// Checks every declared rule rather than only the referenced ones, so a
+    /// typo surfaces on the build that introduced it instead of on the build
+    /// that first uses the family. Remote URLs are checked by name only -- this
+    /// never downloads a font just to validate it.
+    void validateFontFaces() {
+        List<String> errors = new ArrayList<String>();
+        // file name -> the source it was first seen at, so two families sharing
+        // one file stay legal and only genuinely different files collide.
+        Map<String, String> sourceByFileName = new HashMap<String, String>();
+        Map<String, String> familyByFileName = new HashMap<String, String>();
+        for (FontFace face : fontFaces) {
+            String family = face.fontFamily == null ? "(no font-family)" : face.fontFamily.getStringValue();
+            URL url;
+            try {
+                url = face.getURL();
+            } catch (RuntimeException ex) {
+                errors.add("@font-face \"" + family + "\" has an unreadable src URL: " + ex.getMessage());
+                continue;
+            }
+            if (url == null) {
+                errors.add("@font-face \"" + family + "\" has no usable src; "
+                        + "Codename One only supports src: url(...) pointing at a .ttf file");
+                continue;
+            }
+
+            String fileName = fontFileName(url);
+            if (!fileName.endsWith(".ttf")) {
+                errors.add("@font-face \"" + family + "\" points at " + fileName + ". "
+                        + fontExtensionAdvice(fileName));
+                continue;
+            }
+
+            String source = canonicalSource(url);
+            String previousSource = sourceByFileName.put(fileName, source);
+            String previousFamily = familyByFileName.put(fileName, family);
+            if (previousSource != null && !previousSource.equals(source)) {
+                errors.add("@font-face \"" + family + "\" and \"" + previousFamily + "\" resolve to different "
+                        + "files that are both named " + fileName + ". Fonts are deployed next to the theme "
+                        + "resource by file name alone, so one would overwrite the other; rename one of them");
+            }
+
+            if (!"file".equals(url.getProtocol())) {
+                // Remote fonts are downloaded into the CSS directory, so only the name matters here.
+                continue;
+            }
+            File fontFile;
+            try {
+                fontFile = new File(url.toURI());
+            } catch (URISyntaxException ex) {
+                errors.add("@font-face \"" + family + "\" has an unreadable src path: " + url);
+                continue;
+            }
+            if (!fontFile.exists()) {
+                errors.add("@font-face \"" + family + "\" refers to " + fontFile + ", which doesn't exist");
+                continue;
+            }
+            if (!isInsideCssDirectory(fontFile)) {
+                errors.add("@font-face \"" + family + "\" refers to " + fontFile + ", which is outside the "
+                        + "directory holding the CSS file. Only that directory is copied into the build, so "
+                        + "move the font beside the CSS file or into a subdirectory of it");
+                continue;
+            }
+            String contentError = fontContentError(fontFile);
+            if (contentError != null) {
+                errors.add("@font-face \"" + family + "\" refers to " + fontFile.getName() + ", which "
+                        + contentError);
+            }
+        }
+        if (!errors.isEmpty()) {
+            StringBuilder message = new StringBuilder("Invalid @font-face rules in ")
+                    .append(baseURL == null ? "the stylesheet" : baseURL.toString())
+                    .append(':');
+            for (String error : errors) {
+                message.append("\n  - ").append(error);
+            }
+            throw new IllegalArgumentException(message.toString());
+        }
+    }
+
+    /// The file name the runtime will see, which is what `Font.createTrueTypeFont`
+    /// validates and what the deploy copy is keyed on. Percent-escapes are decoded
+    /// because the downloaded file lands under the decoded name.
+    private static String fontFileName(URL url) {
+        String path = url.getPath();
+        try {
+            path = java.net.URLDecoder.decode(path, "UTF-8");
+        } catch (UnsupportedEncodingException ex) {
+            // UTF-8 is always present; fall through with the raw path.
+        }
+        int slash = path.lastIndexOf('/');
+        return slash < 0 ? path : path.substring(slash + 1);
+    }
+
+    /// Reads the font the way the rest of the toolchain will, so a file that
+    /// can't actually be used is caught here instead of on a device.
+    ///
+    /// Two failures hide until far too late otherwise. A file the font parser
+    /// rejects leaves `EditorTTFFont.actualFont` null -- `refresh()` swallows
+    /// the Throwable -- and then dies as a bare NPE inside `EditableResources`
+    /// `save()` naming no rule. And a font with no PostScript name works in the
+    /// simulator and on Android, which look the font up by file name, while iOS
+    /// resolves purely by the PostScript name written into the resource and so
+    /// falls back to the system font on the device.
+    ///
+    /// @return the problem phrased to follow "which ...", or null when the font
+    /// is usable
+    private static String fontContentError(File fontFile) {
+        java.awt.Font parsed;
+        try {
+            parsed = java.awt.Font.createFont(java.awt.Font.TRUETYPE_FONT, fontFile);
+        } catch (Exception ex) {
+            return "isn't a font file Codename One can read (" + ex.getMessage() + ")";
+        }
+        String psName = parsed.getPSName();
+        if (psName == null || psName.trim().length() == 0) {
+            return "has no PostScript name. iOS looks fonts up by that name, so this would render "
+                    + "in the simulator and on Android but fall back to the system font on an iOS device";
+        }
+        return null;
+    }
+
+    /// Identity of the file a rule points at, used to tell a genuine name
+    /// collision apart from two families deliberately sharing one font file.
+    private static String canonicalSource(URL url) {
+        if ("file".equals(url.getProtocol())) {
+            try {
+                return new File(url.toURI()).getCanonicalPath();
+            } catch (URISyntaxException ex) {
+                return url.toString();
+            } catch (IOException ex) {
+                return url.toString();
+            }
+        }
+        return url.toString();
+    }
+
+    /// The constraint is the file NAME, not the outline format: the runtime
+    /// check is `fileName.endsWith(".ttf")` and the iOS build only registers
+    /// files matching that. Worth being precise about, because "convert to
+    /// TrueType" and "rename the file" are different amounts of work and only
+    /// one of them is actually required.
+    private static String fontExtensionAdvice(String fileName) {
+        String lower = fileName.toLowerCase();
+        if (lower.endsWith(".otf")) {
+            return "Codename One loads fonts by a file name ending in .ttf, so an .otf never reaches "
+                    + "the device -- convert it to TrueType";
+        }
+        if (lower.endsWith(".ttf")) {
+            return "the extension has to be lower-case .ttf; the runtime check is case-sensitive";
+        }
+        return "Codename One loads fonts by a file name ending in .ttf";
+    }
+
+    /// Containment is judged against `baseURL`, the stylesheet relative `src`
+    /// URLs are resolved against, rather than `cssFile` -- the latter is a
+    /// placeholder unless a caller sets it, so using it would reject every
+    /// perfectly good font.
+    private boolean isInsideCssDirectory(File fontFile) {
+        if (baseURL == null || !"file".equals(baseURL.getProtocol())) {
+            return true;
+        }
+        File cssDir;
+        try {
+            cssDir = new File(baseURL.toURI()).getAbsoluteFile().getParentFile();
+        } catch (URISyntaxException ex) {
+            return true;
+        }
+        if (cssDir == null) {
+            return true;
+        }
+        try {
+            String root = cssDir.getCanonicalPath() + File.separator;
+            return fontFile.getCanonicalPath().startsWith(root);
+        } catch (IOException ex) {
+            // Can't prove it's outside, so don't fail the build on it.
+            return true;
+        }
+    }
+
     public void updateResources() {
+        validateFontFaces();
         if (res != null) {
             Map<String, Object> themeData = res.getTheme(themeName);
             if (themeData != null) {