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

@@ -179,4 +179,5 @@ void superComplete(T value) {
     void superError(Throwable t) {
         super.error(t);
     }
+
 }

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