Watch apps: one entry point, a phone-watch channel, and a simulator that can run the pair

.github/workflows/ios-packaging.yml

@@ -108,10 +108,18 @@ jobs:
               | sort | xargs shasum -a 256 | shasum -a 256 | awk '{print $1}')
           POM_HASH=$(find . -name 'pom.xml' -not -path './scripts/*' 2>/dev/null \
               | sort | xargs shasum -a 256 | shasum -a 256 | awk '{print $1}')
+          # The build INVOCATION belongs in the key, not just the sources. Derived data
+          # embeds the SDK, destination and per-target product layout an invocation
+          # produced; restoring a tree built by a different one leaves Xcode's build
+          # database claiming targets are up to date when their products are absent
+          # ("Build input file cannot be found ... output of a script phase").
           SCRIPT_HASH=$(shasum -a 256 \
               scripts/setup-workspace.sh \
               scripts/build-ios-port.sh \
               scripts/build-native-themes.sh \
+              scripts/build-ios-app.sh \
+              scripts/run-ios-device-release-build.sh \
+              scripts/run-ios-ui-tests.sh \
               .github/workflows/_build-ios-port.yml \
               | shasum -a 256 | awk '{print $1}')
           echo "hash=${SRC_HASH:0:16}-${POM_HASH:0:16}-${SCRIPT_HASH:0:16}" >> "$GITHUB_OUTPUT"
@@ -165,8 +173,10 @@ jobs:
         with:
           path: ${{ runner.temp }}/cn1-ios-device-release-derived
           key: ${{ runner.os }}-ios-device-release-derived-${{ steps.src_hash.outputs.hash }}
-          restore-keys: |
-            ${{ runner.os }}-ios-device-release-derived-
+          # Deliberately no restore-keys prefix. A partial match here restores derived
+          # data produced by a DIFFERENT build invocation, and a stale Xcode build
+          # database is worse than a cold compile: it reports success for targets it
+          # skipped. An exact hit or nothing.
 
       - name: Build Release iOS device app without signing
         env:

CodenameOne/src/com/codename1/impl/CodenameOneImplementation.java

@@ -6000,6 +6000,18 @@ public boolean isCarConnected() {
         return b != null && b.isConnected();
     }
 
+    /// Returns the platform bridge that carries the `com.codename1.wearable` phone-to-watch API over
+    /// the native transport (Apple's `WCSession` / Google's Wearable Data Layer), or null when this
+    /// device has no wearable counterpart (the base implementation). When null, the
+    /// `com.codename1.wearable` API degrades to a harmless no-op.
+    ///
+    /// #### Returns
+    ///
+    /// the wearable bridge, or null when unsupported
+    public com.codename1.wearable.spi.WearableBridge getWearableBridge() {
+        return null;
+    }
+
     /// Returns the platform bridge used by the `com.codename1.surfaces` API to render external
     /// surfaces (home-screen widgets and live activities). Ports supporting surfaces override
     /// this; the base implementation returns null which renders the whole API an inert no-op.

CodenameOne/src/com/codename1/impl/health/EdtResult.java

@@ -98,4 +98,72 @@ void superComplete(T value) {
     void superError(Throwable t) {
         super.error(t);
     }
+
+    /// Marshalling `complete` is not enough on its own: a listener attached
+    /// *after* the resource has settled is run by
+    /// `AsyncResource.ready`/`except` inline, on whichever thread attaches it.
+    ///
+    /// That is the whole contract leaking back out. The window is small but
+    /// entirely reachable -- `openHealthSettings` and `openProviderSetup`
+    /// complete before they return, so an off-EDT caller writing the ordinary
+    /// `openHealthSettings().onResult(cb)` races the `callSerially` above
+    /// between two adjacent statements. Win the race and the callback arrives
+    /// on the EDT; lose it and the same line of app code delivers off the EDT.
+    /// It is exactly the "may or may not be on the EDT" asymmetry this class
+    /// exists to remove, and it fails intermittently, which is worse than
+    /// failing always.
+    ///
+    /// So the guarantee is applied where the callback is *invoked* rather than
+    /// where the resource is completed: whatever thread gets here, delivery
+    /// hops to the EDT if it is not already on it. Already on the EDT still
+    /// runs inline, so the no-runnable-per-link property above is kept.
+    @Override
+    public com.codename1.util.AsyncResource<T> ready(
+            final com.codename1.util.SuccessCallback<T> callback,
+            com.codename1.util.EasyThread t) {
+        if (t != null) {
+            // An explicit thread is the caller overriding the default on
+            // purpose; honouring the request beats honouring the default.
+            return super.ready(callback, t);
+        }
+        return super.ready(new OnEdt<T>(callback), null);
+    }
+
+    /// `except` is deliberately NOT wrapped the same way.
+    ///
+    /// A late `except` on an already-failed resource fires synchronously, and
+    /// that is relied on to read an error back without waiting -- see
+    /// `HealthFallbackTest.errorOf`, which documents the trick and shares it
+    /// with `BtTestUtil`. Hopping the error to the EDT breaks every such
+    /// reader: the callback has not run yet when the value is read, so the
+    /// error reads as null and a failing call looks like a succeeding one.
+    ///
+    /// So the asymmetry is left in place on purpose rather than overlooked.
+    /// Closing it means changing that read pattern everywhere it is used,
+    /// which is a wider behavioural change than the delivery bug this fixes
+    /// and belongs in its own change.
+
+    /// Named, not anonymous, for the same SpotBugs reason as `Deliver`.
+    private static final class OnEdt<X> implements com.codename1.util.SuccessCallback<X> {
+
+        private final com.codename1.util.SuccessCallback<X> delegate;
+
+        OnEdt(com.codename1.util.SuccessCallback<X> delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public void onSucess(final X value) {
+            if (Display.getInstance().isEdt()) {
+                delegate.onSucess(value);
+                return;
+            }
+            Display.getInstance().callSerially(new Runnable() {
+                @Override
+                public void run() {
+                    delegate.onSucess(value);
+                }
+            });
+        }
+    }
 }

CodenameOne/src/com/codename1/surfaces/SurfaceSerializer.java

@@ -50,6 +50,18 @@ public final class SurfaceSerializer {
     private SurfaceSerializer() {
     }
 
+    /// True when the timeline carries a layout for at least one size family. Iterating the enum
+    /// rather than naming families keeps this correct as the catalog grows -- the watch
+    /// complication families joined it without touching this method.
+    private static boolean hasAnyExplicitContent(WidgetTimeline timeline) {
+        for (WidgetSize size : WidgetSize.values()) {
+            if (timeline.getExplicitContent(size) != null) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /// Serializes a widget timeline.
     ///
     /// #### Parameters
@@ -63,11 +75,7 @@ private SurfaceSerializer() {
     /// the timeline JSON
     public static String serializeTimeline(String kindId, WidgetTimeline timeline,
             Map<String, byte[]> imagesOut) {
-        if (timeline.getDefaultContent() == null
-                && timeline.getContent(WidgetSize.SMALL) == null
-                && timeline.getContent(WidgetSize.MEDIUM) == null
-                && timeline.getContent(WidgetSize.LARGE) == null
-                && timeline.getContent(WidgetSize.LOCKSCREEN) == null) {
+        if (timeline.getDefaultContent() == null && !hasAnyExplicitContent(timeline)) {
             throw new IllegalArgumentException("A widget timeline needs content: call "
                     + "setContent(...) before publishing");
         }

CodenameOne/src/com/codename1/surfaces/WidgetSize.java

@@ -22,15 +22,41 @@
  */
 package com.codename1.surfaces;
 
-/// The size families a widget kind supports. iOS maps these to the WidgetKit families
-/// (`systemSmall` / `systemMedium` / `systemLarge` and `accessoryRectangular` for `LOCKSCREEN`);
-/// Android and desktop treat them as size hints. `LOCKSCREEN` is ignored on Android in this
-/// version.
+/// The size families a widget kind supports.
+///
+/// The first four are the phone families: iOS maps them to the WidgetKit families
+/// (`systemSmall` / `systemMedium` / `systemLarge`, and `accessoryRectangular` for `LOCKSCREEN`);
+/// Android and desktop treat them as size hints, and `LOCKSCREEN` is ignored on Android.
+///
+/// The `WATCH_*` families are **complications** -- the small live readouts on a watch face. They
+/// live here rather than in an API of their own because they are the same concept as a widget:
+/// content-driven, rendered while your app is not running, and fed by the same [WidgetTimeline]. On
+/// Apple a complication is literally a WidgetKit widget in an accessory family; on Wear OS the
+/// simple families become complication data and the richer ones become a Tile.
+///
+/// Design them for a glance. A complication is a few dozen pixels someone reads in under a second,
+/// so a `SurfaceVector` gauge or a single number beats any layout that has to be read.
 public enum WidgetSize {
+    /// Small square home-screen widget. iOS `systemSmall`.
     SMALL("small"),
+    /// Medium home-screen widget. iOS `systemMedium`.
     MEDIUM("medium"),
+    /// Large home-screen widget. iOS `systemLarge`.
     LARGE("large"),
-    LOCKSCREEN("lockscreen");
+    /// Lock-screen widget. iOS `accessoryRectangular`.
+    LOCKSCREEN("lockscreen"),
+    /// Round complication -- the corner or centre slots of a watch face. iOS `accessoryCircular`;
+    /// Wear OS `RANGED_VALUE` or `MONOCHROMATIC_IMAGE`. Room for a gauge or one glyph.
+    WATCH_CIRCULAR("watchCircular"),
+    /// Wide complication, a band across the watch face. iOS `accessoryRectangular`; Wear OS
+    /// `LONG_TEXT`, or a Tile when the layout is richer than text. The roomiest family.
+    WATCH_RECTANGULAR("watchRectangular"),
+    /// One line of text alongside the time. iOS `accessoryInline`; Wear OS `SHORT_TEXT`. Text only --
+    /// anything else is dropped.
+    WATCH_INLINE("watchInline"),
+    /// Curved complication hugging the bezel of a round face. iOS `accessoryCorner`; renders as the
+    /// circular family on Wear OS, which has no corner slot.
+    WATCH_CORNER("watchCorner");
 
     private final String jsonName;
 
@@ -42,4 +68,33 @@ public enum WidgetSize {
     public String getJsonName() {
         return jsonName;
     }
+
+    /// True for the watch complication families, which are published to a watch face rather than to
+    /// a home or lock screen.
+    ///
+    /// #### Returns
+    ///
+    /// true if this is a complication family
+    public boolean isWatchFamily() {
+        return this == WATCH_CIRCULAR || this == WATCH_RECTANGULAR
+                || this == WATCH_INLINE || this == WATCH_CORNER;
+    }
+
+    /// Resolves a wire-format name back to its family.
+    ///
+    /// #### Parameters
+    ///
+    /// - `jsonName`: the name produced by [#getJsonName()]
+    ///
+    /// #### Returns
+    ///
+    /// the matching family, or null when the name is unknown
+    public static WidgetSize fromJsonName(String jsonName) {
+        for (WidgetSize s : values()) {
+            if (s.jsonName.equals(jsonName)) {
+                return s;
+            }
+        }
+        return null;
+    }
 }

CodenameOne/src/com/codename1/surfaces/WidgetTimeline.java

@@ -73,10 +73,12 @@ public Map<String, Object> getState() {
     }
 
     private SurfaceNode defaultContent;
-    private SurfaceNode smallContent;
-    private SurfaceNode mediumContent;
-    private SurfaceNode largeContent;
-    private SurfaceNode lockscreenContent;
+    /// Per-family layout overrides. A map rather than a field per family: the catalog grows (the
+    /// watch accessory families joined the phone ones) and a switch per accessor did not. A plain
+    /// HashMap rather than an EnumMap -- the Codename One runtime has no EnumMap, and lookups here
+    /// are by key so the ordering an EnumMap would give buys nothing.
+    private final Map<WidgetSize, SurfaceNode> overrides =
+            new java.util.HashMap<WidgetSize, SurfaceNode>();
     private final List<Entry> entries = new ArrayList<Entry>();
     private int reloadPolicy = RELOAD_AT_END;
 
@@ -105,21 +107,12 @@ public WidgetTimeline setContent(SurfaceNode root) {
     ///
     /// this timeline, for chaining
     public WidgetTimeline setContent(WidgetSize size, SurfaceNode root) {
-        switch (size) {
-            case SMALL:
-                smallContent = root;
-                break;
-            case MEDIUM:
-                mediumContent = root;
-                break;
-            case LARGE:
-                largeContent = root;
-                break;
-            case LOCKSCREEN:
-                lockscreenContent = root;
-                break;
-            default:
-                break;
+        if (size != null) {
+            if (root == null) {
+                overrides.remove(size);
+            } else {
+                overrides.put(size, root);
+            }
         }
         return this;
     }
@@ -172,41 +165,14 @@ public WidgetTimeline setReloadPolicy(int policy) {
     ///
     /// the layout root, or null when neither an override nor a default was set
     public SurfaceNode getContent(WidgetSize size) {
-        SurfaceNode override = null;
-        switch (size) {
-            case SMALL:
-                override = smallContent;
-                break;
-            case MEDIUM:
-                override = mediumContent;
-                break;
-            case LARGE:
-                override = largeContent;
-                break;
-            case LOCKSCREEN:
-                override = lockscreenContent;
-                break;
-            default:
-                break;
-        }
+        SurfaceNode override = size == null ? null : overrides.get(size);
         return override != null ? override : defaultContent;
     }
 
     /// Returns the explicit per-size override, or null when the size family falls back to the
     /// default content. Used by the serializer so only real overrides are emitted per size.
     SurfaceNode getExplicitContent(WidgetSize size) {
-        switch (size) {
-            case SMALL:
-                return smallContent;
-            case MEDIUM:
-                return mediumContent;
-            case LARGE:
-                return largeContent;
-            case LOCKSCREEN:
-                return lockscreenContent;
-            default:
-                return null;
-        }
+        return size == null ? null : overrides.get(size);
     }
 
     /// Returns the layout used for size families without an explicit override, or null.

CodenameOne/src/com/codename1/ui/Display.java

@@ -4713,6 +4713,18 @@ public com.codename1.car.spi.CarBridge getCarBridge() {
         return impl.getCarBridge();
     }
 
+    /// Returns the platform bridge used by the `com.codename1.wearable` API to talk to the
+    /// counterpart watch or phone app, or null when this device has no wearable counterpart.
+    /// Internal -- application code uses the `com.codename1.wearable` API rather than this bridge
+    /// directly.
+    ///
+    /// #### Returns
+    ///
+    /// the wearable bridge, or null
+    public com.codename1.wearable.spi.WearableBridge getWearableBridge() {
+        return impl.getWearableBridge();
+    }
+
     /// Returns the platform bridge used by the `com.codename1.surfaces` API to render external
     /// surfaces (home-screen widgets and live activities), or null when unsupported on this port.
     /// Internal -- application code uses the `com.codename1.surfaces` API rather than this bridge