Gates for the developer guide defects Asciidoctor cannot see

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...
 

.github/workflows/developer-guide-docs.yml

@@ -50,8 +50,13 @@ jobs:
  docs:
  - 'docs/developer-guide/**'
  - 'docs/demos/common/src/main/snippets/**'
- - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
- - 'scripts/developer-guide/validate-guide-snippets.py'
+ # The whole directory, not two named files. on.pull_request.paths
+ # already triggers on scripts/developer-guide/**, so a change to any
+ # other script here started the workflow while leaving this filter
+ # false -- which skipped the very steps that script governs. A
+ # change to compare-screenshots.py could have merged without the
+ # screenshot check ever running it.
+ - 'scripts/developer-guide/**'
  - '.github/workflows/developer-guide-docs.yml'
  # Triggering the workflow is not enough on its own: the HTML and PDF
  # build and the steps beside it are gated on this filter, so the
@@ -122,6 +127,7 @@ jobs:
  run: |
  set -euo pipefail
  GENERATED_DIR="$RUNNER_TEMP/pre-advanced-theming-screenshots"
+ echo "GUIDE_GENERATED_SCREENSHOTS=$GENERATED_DIR" >> "$GITHUB_ENV"
  rm -rf "$GENERATED_DIR"
  mkdir -p "$GENERATED_DIR"
  xvfb-run -a mvn -B -ntp \
@@ -131,23 +137,25 @@ jobs:
  -P guide-screenshot-generator \
  -Dguide.screenshot.output="$GENERATED_DIR" \
  verify
- COUNT="$(find "$GENERATED_DIR" -maxdepth 1 -type f -name '*.png' | wc -l | tr -d ' ')"
- if [ "$COUNT" != "24" ]; then
- echo "::error::Expected 24 generated pre-Advanced Theming screenshots, found $COUNT"
- exit 1
- fi
- for generated in "$GENERATED_DIR"/*.png; do
- name="$(basename "$generated")"
- committed="docs/developer-guide/img/$name"
- if [ ! -f "$committed" ]; then
- echo "::error::Generated screenshot has no committed counterpart: $name"
- exit 1
- fi
- if ! cmp -s "$generated" "$committed"; then
- echo "::error::Committed screenshot is stale: $name"
- exit 1
- fi
- done
+ pip install --user --quiet Pillow
+ # Byte equality is still the rule; a figure only gets a bounded
+ # difference if it carries a .tolerance sidecar saying why.
+ python3 scripts/developer-guide/compare-screenshots.py \
+ --generated "$GENERATED_DIR" \
+ --committed docs/developer-guide/img \
+ --expected-count 24
+
+ # When the byte compare fails, the message names the file but not what it
+ # actually rendered, which leaves no way to tell a real regression from an
+ # environment difference. Publishing what this runner produced makes the
+ # two distinguishable without adding a debugging round trip to CI.
+ - name: Upload generated screenshots when they do not match
+ if: failure() && env.GUIDE_GENERATED_SCREENSHOTS != ''
+ uses: actions/upload-artifact@v7
+ with:
+ name: guide-generated-screenshots
+ path: ${{ env.GUIDE_GENERATED_SCREENSHOTS }}
+ if-no-files-found: warn
 
  - name: Verify developer guide images are referenced
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
@@ -271,6 +279,25 @@ jobs:
  echo "Asciidoctor exited with status $STATUS — the final quality-gate step will fail the build." >&2
  fi
 
+ # These four cover defects the gates above are structurally blind to: a
+ # chapter swallowed by the one before it, a cross-reference that resolves
+ # to nothing, prose that promises a code block which is not there, and a
+ # link the website does not serve. Asciidoctor reports none of them, and
+ # every one of them shipped. The structure and cross-reference checks
+ # render the book, so they must run after the Asciidoctor install.
+ - name: Check developer guide structure, cross-references, code blocks and links
+ run: |
+ set -euo pipefail
+ python3 scripts/developer-guide/check-guide-structure.py
+ python3 scripts/developer-guide/check-guide-xrefs.py
+ python3 scripts/developer-guide/check-missing-code-blocks.py
+ # Note this only catches a link the GUIDE breaks. When the website
+ # moves the route instead -- a page renamed, deleted or re-slugged --
+ # the same script runs from website-docs.yml, which triggers on
+ # docs/website/**. Putting those paths here would run this whole job
+ # (maven install, demo build, screenshots) for every blog post.
+ python3 scripts/developer-guide/check-guide-links.py
+
  - name: Build Developer Guide HTML and PDF
  if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
  run: |

.github/workflows/website-docs.yml

@@ -20,6 +20,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # The developer guide this site renders includes a build hint table that is
  # generated rather than committed, so a change to the catalog or to the
  # renderer changes the published page without touching docs/. The
@@ -46,6 +50,10 @@ on:
  - 'vm/ByteCodeTranslator/**'
  - 'vm/JavaAPI/**'
  - 'CodenameOne/src/**'
+ # The other root build_javadocs.sh generates from, and the other one
+ # check-guide-links.py indexes. Without it, deleting a linked CLDC type
+ # merges unvalidated and the next scheduled build is where it surfaces.
+ - 'Ports/CLDC11/src/**'
  # As above: the build hint table is generated, not committed.
  - 'maven/build-hint-catalog/**'
  - 'maven/build-hint-tools/**'
@@ -277,6 +285,17 @@ jobs:
  --root-dir public
  public/**/*.html
 
+ # The developer guide links into this site, so a page renamed, deleted or
+ # re-slugged here breaks the guide. The check lives in THIS workflow rather
+ # than in developer-guide-docs.yml because it is the route data that
+ # changed: widening that workflow's paths to docs/website/** would run the
+ # full guide build -- maven install, demo build, screenshot generation --
+ # on every blog post the daily publisher pushes, to run one Python script.
+ # This job already triggers on docs/website/**, and the check needs nothing
+ # but a checkout.
+ - name: Check developer guide links against the routes this site serves
+ run: python3 scripts/developer-guide/check-guide-links.py
+
  - name: Reject absolute codenameone.com links
  run: |
  set -euo pipefail

docs/demos/common/src/main/java/com/codenameone/developerguide/screenshots/PreAdvancedThemingScreenshots.java

@@ -1,17 +1,41 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
 package com.codenameone.developerguide.screenshots;
 
 import com.codename1.components.SpanLabel;
 import com.codenameone.developerguide.snippets.generated.BasicsJava034Snippet;
 import com.codename1.ui.Button;
 import com.codename1.ui.Component;
 import com.codename1.ui.Container;
+import com.codename1.ui.Display;
 import com.codename1.ui.CN;
 import com.codename1.ui.FontImage;
 import com.codename1.ui.Font;
 import com.codename1.ui.Form;
 import com.codename1.ui.Graphics;
 import com.codename1.ui.Image;
 import com.codename1.ui.Label;
+import com.codename1.ui.TextArea;
 import com.codename1.ui.TextField;
 import com.codename1.ui.layouts.BorderLayout;
 import com.codename1.ui.layouts.BoxLayout;
@@ -40,10 +64,33 @@ public final class PreAdvancedThemingScreenshots {
  private static final int BLUE = 0x0b57d0;
  private static final int GREEN = 0x06a806;
  private static final int WHITE = 0xffffff;
- private static final Font TITLE_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(35, Font.STYLE_PLAIN);
- private static final Font BLOCK_FONT = Font.createSystemFont(Font.FACE_SYSTEM, Font.STYLE_PLAIN, Font.SIZE_LARGE)
- .derive(24, Font.STYLE_PLAIN);
+ private static final Font TITLE_FONT = screenshotFont(35);
+ private static final Font BLOCK_FONT = screenshotFont(24);
+ /// Sized to match the height the theme's own default font had (13px), so
+ /// pinning the face on components the block styling does not touch keeps
+ /// their layout exactly where it was.
+ private static final Font FIELD_FONT = screenshotFont(11);
+
+ /// Loads a figure font from the port's bundled Roboto rather than from the host.
+ ///
+ /// `Font.createSystemFont` resolves through `JavaSEPort.fontFaceSystem`, which is
+ /// "Arial" on macOS and Linux alike. Arial exists on a developer's Mac and not on a
+ /// stock CI runner, so AWT silently substitutes a different face and every glyph in
+ /// every figure changes -- which is why none of these screenshots could be
+ /// regenerated outside CI and byte-compared against what was committed. The
+ /// `native:` scheme reads `/com/codename1/impl/javase/Roboto-*.ttf` off the
+ /// classpath, so the result does not depend on what the machine happens to have
+ /// installed. It is also what this project's font rule requires everywhere.
+ private static Font screenshotFont(int pixelSize) {
+ Font font = Font.createTrueTypeFont("native:MainRegular", "native:MainRegular");
+ if (font == null) {
+ // Falling back to a host font would quietly restore the very
+ // non-determinism this exists to remove, so refuse instead.
+ throw new IllegalStateException(
+ "the native font scheme is unavailable, so figures would render with a host font");
+ }
+ return font.derive(pixelSize, Font.STYLE_PLAIN);
+ }
 
  private PreAdvancedThemingScreenshots() {
  }
@@ -53,6 +100,32 @@ public interface ScreenshotSink {
  }
 
  public static void generate(ScreenshotSink sink) throws IOException {
+ // JavaSEPort.loadTrueTypeFont has an earlier branch for native: fonts:
+ // when isIOS is set -- which loadSkinFile does for any skin whose
+ // systemFontFamily contains "helvetica" -- it resolves to the first
+ // INSTALLED SF or Helvetica family and never reaches the bundled Roboto.
+ // This generator never loads a skin, so that branch is not taken, and the
+ // measurement agrees: figures rendered on a Mac match the Linux runner
+ // byte for byte, which could not happen if one side were using Helvetica
+ // Neue. Guard it anyway, because a future change that loads a skin here
+ // would put the host's fonts back into the output without any other
+ // symptom.
+ String platform = Display.getInstance().getPlatformName();
+ if ("ios".equals(platform)) {
+ throw new IllegalStateException(
+ "an iOS skin is active, so native: fonts would resolve to installed "
+ + "system faces instead of the bundled ones and these figures would "
+ + "stop being reproducible off this machine");
+ }
+
+ // MigLayout picks its default gaps from PlatformDefaults, which reads
+ // System.getProperty("os.name") and returns MAC_OSX, GNOME or WINDOWS_XP.
+ // The gaps differ per platform, so mig-layout.png came out with macOS
+ // spacing on a Mac and GNOME spacing on the Linux runner -- a 12.8% pixel
+ // difference that has nothing to do with fonts. Pin it so the figure shows
+ // the same thing wherever it is generated.
+ com.codename1.ui.layouts.mig.PlatformDefaults.setPlatform(
+ com.codename1.ui.layouts.mig.PlatformDefaults.GNOME);
  write(sink, "flow-layout.png", flow("Flow Layout", Component.LEFT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-center.png", flow("Flow Layout", Component.CENTER, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
  write(sink, "flow-layout-right.png", flow("Flow Layout", Component.RIGHT, Component.TOP), PORTRAIT_WIDTH, PORTRAIT_HEIGHT);
@@ -328,6 +401,22 @@ private static void applyScreenshotStyle(Form form) {
  private static void applyBlockStyleToContent(Container container) {
  for (int i = 0; i < container.getComponentCount(); i++) {
  Component component = container.getComponentAt(i);
+ // Pin the font on EVERY component rather than on the types that also
+ // get block colours. Anything left on the theme's default font
+ // resolves through the host, and that is what made
+ // guibuilder-2-insets-3.png -- the only figure containing a
+ // TextField -- differ between a Mac and CI while the other 23
+ // matched byte for byte. Enumerating the types that carry text
+ // would leave the next one to be added broken in the same way.
+ component.getAllStyles().setFont(FIELD_FONT);
+ if (component instanceof TextArea) {
+ // The hint is painted by a Label that is not in the component
+ // tree, so the walk above never reaches it.
+ Label hint = ((TextArea) component).getHintLabel();
+ if (hint != null) {
+ hint.getAllStyles().setFont(FIELD_FONT);
+ }
+ }
  if (component instanceof Label || component instanceof Button) {
  styleBlock(component);
  }

docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh

@@ -1,5 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
 // tag::working-with-windows-bash-001[]
-mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device
+mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device
 // end::working-with-windows-bash-001[]

docs/developer-guide/Advanced-Theming.asciidoc

@@ -728,7 +728,7 @@ Will set the foreground color of the https://www.codenameone.com/javadoc/com/cod
 
 When a Codename One https://www.codenameone.com/javadoc/com/codename1/ui/Component.html[Component] is instantiated it requests a https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] object from the https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html[UIManager] class. The `Style` object is based on the settings within the theme and can be modified through code or by using the theme.
 
-You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--[refreshTheme()] method.
+You can replace the theme dynamically in runtime and refresh the styles assigned to the various components using the https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme()[refreshTheme()] method.
 
 NOTE: It's a common mistake to invoke `refreshTheme()` without actually changing the theme. You see developers doing it when all they need is a `repaint()` or `revalidate()`. Since `refreshTheme()` is **** expensive recommend that you don't use it unless you need to...