Add a device runtime that runs pushed Codename One apps on a phone

Codename One apps run two ways today: the JavaSE simulator, which is not a
device, or a cloud device build, which costs minutes per iteration. This adds a
third: install one app on a phone, and from then on push a project to it from an
IDE and watch it run natively in seconds.

The app is not a shell around a compiled build. Pushed classes are interpreted
on the device against the framework already compiled into it, so nothing is
built, signed or installed between edits.

How the pieces fit
------------------

com.codename1.interp is the interpreter: one interpreted frame per real frame,
so Display.invokeAndBlock and every blocking idiom built on it still work. A
per-thread fuel counter bounds runaway code, and the budget is per entry into
the interpreter rather than per session -- measuring it per session kills every
callback that arrives later than the budget, which in an application whose whole
life is callbacks is every button press.

Interpreted classes reach the framework through InterpLinker: invoke thunks on
iOS, reflection on Android. A linker must dispatch on the receiver's class, not
the call site's declared type -- list.add(x) names java.util.List, and resolving
from there finds AbstractList.add, whose body throws.

Extending a framework class needs an object the framework accepts, which neither
platform can define at run time. Generated shims provide it: every public,
non-final, constructible class and every public interface the device exposes,
derived by scanning the framework jar and codenameone-java-runtime rather than
curated. A hand-maintained list is a promise that applications only subclass
what somebody anticipated, and its failure mode is not an error but an override
that is silently never called.

Lambdas and method references are rewritten into real classes when the bundle is
written, since neither target has a runtime invokedynamic. Enums are answered by
the interpreter, java.lang.Enum having no shim and needing none.

Store compliance is built in rather than bolted on: the runtime refuses to load
a bundle whose sources it cannot show, and shows them.

Verified
--------

4798 core tests, 506 translator tests, 43 interpreter tests, SpotBugs at zero,
and a 20-program device battery (scripts/devruntime-probes) passing on both an
Android emulator and the iOS simulator -- including a four-file, three-package
application entered through Lifecycle rather than main.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: shai-almog

.github/workflows/device-runtime-store.yml

@@ -0,0 +1,208 @@
+# Weekly build of the device runtime for testers.
+#
+# Uploads to Google Play internal testing and to TestFlight. It does not promote
+# to production and does not submit for App Store review -- see
+# scripts/cn1-device-runtime/store/README.md for why that is deliberate.
+#
+# Without credentials the job reports what is missing and stops. It never
+# publishes half of a release.
+name: Device runtime store build
+
+on:
+  schedule:
+    # Monday morning, so a failure has a working week in front of it.
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Build and check credentials without uploading'
+        type: boolean
+        default: false
+
+concurrency:
+  group: device-runtime-store
+  cancel-in-progress: false
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    outputs:
+      android: ${{ steps.check.outputs.android }}
+      ios: ${{ steps.check.outputs.ios }}
+    steps:
+      - id: check
+        name: Which stores are configured
+        env:
+          PLAY_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
+          KEYSTORE: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ASC_KEY: ${{ secrets.APPSTORE_PRIVATE_KEY }}
+          IOS_CERT: ${{ secrets.IOS_DIST_CERT_P12 }}
+        run: |
+          android=false
+          ios=false
+          if [ -n "$PLAY_JSON" ] && [ -n "$KEYSTORE" ]; then android=true; fi
+          if [ -n "$ASC_KEY" ] && [ -n "$IOS_CERT" ]; then ios=true; fi
+          echo "android=$android" >> "$GITHUB_OUTPUT"
+          echo "ios=$ios" >> "$GITHUB_OUTPUT"
+          echo "### Device runtime store build" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Store | Configured |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|---|---|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Google Play | $android |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| App Store | $ios |" >> "$GITHUB_STEP_SUMMARY"
+          if [ "$android" = false ] && [ "$ios" = false ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "No publishing credentials are present, so nothing was uploaded." >> "$GITHUB_STEP_SUMMARY"
+            echo "The secrets each store needs are listed in" >> "$GITHUB_STEP_SUMMARY"
+            echo "\`scripts/cn1-device-runtime/store/README.md\`." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+  android:
+    needs: preflight
+    if: needs.preflight.outputs.android == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: JDK 8 for the framework, JDK 17 for the Android port
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: |
+            8
+            17
+
+      - name: Build the framework and the Android port
+        run: |
+          cd maven
+          mvn -B -q -DskipTests install -pl core,parparvm -am
+          mvn -B -q -DskipTests -Pcompile-android install -pl android
+
+      - name: Regenerate and verify the shims
+        # The shims are the app's compiled contract with pushed code. The script
+        # fails if one will not compile, if a load-bearing shim is missing, or if
+        # generation is not reproducible -- all of which are release blockers.
+        run: scripts/generate-interp-shims.sh
+
+      - name: Build the app bundle
+        env:
+          JAVA17_HOME: ${{ env.JAVA_HOME_17_X64 }}
+        run: |
+          cd scripts/cn1-device-runtime
+          mvn -B -q package -DskipTests \
+            -Dcodename1.platform=android \
+            -Dcodename1.buildTarget=android-source \
+            -Dopen=false
+
+      - name: Sign and assemble
+        env:
+          KEYSTORE_B64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          gradle_dir="$(find scripts/cn1-device-runtime/android/target -maxdepth 1 \
+            -name '*-android-source' -type d | head -1)"
+          [ -n "$gradle_dir" ] || { echo "no gradle project was generated" >&2; exit 1; }
+          echo "$KEYSTORE_B64" | base64 -d > "$gradle_dir/upload.keystore"
+          cd "$gradle_dir"
+          ./gradlew --no-daemon bundleRelease \
+            -Pandroid.injected.signing.store.file=upload.keystore \
+            -Pandroid.injected.signing.store.password="$KEYSTORE_PASSWORD" \
+            -Pandroid.injected.signing.key.alias="$KEY_ALIAS" \
+            -Pandroid.injected.signing.key.password="$KEY_PASSWORD"
+
+      - name: Upload to internal testing
+        if: ${{ !inputs.dry_run }}
+        uses: r0adkll/upload-google-play@v1
+        with:
+          serviceAccountJsonPlainText: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
+          packageName: com.codenameone.devruntime
+          releaseFiles: scripts/cn1-device-runtime/android/target/*-android-source/app/build/outputs/bundle/release/*.aab
+          track: internal
+          status: completed
+          whatsNewDirectory: scripts/cn1-device-runtime/fastlane/metadata/android/en-US/changelogs
+
+  ios:
+    needs: preflight
+    if: needs.preflight.outputs.ios == 'true'
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: JDK 8 for the framework, JDK 17 for the translator
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: |
+            8
+            17
+
+      - name: Build the framework, translator and iOS port
+        run: |
+          cd maven
+          mvn -B -q -DskipTests install -pl core,parparvm,ios -am
+
+      - name: Regenerate and verify the shims
+        run: scripts/generate-interp-shims.sh
+
+      - name: Translate to Xcode
+        env:
+          JAVA17_HOME: ${{ env.JAVA_HOME_17_X64 }}
+        run: |
+          cd scripts/cn1-device-runtime
+          mvn -B -q package -DskipTests \
+            -Dcodename1.platform=ios \
+            -Dcodename1.buildTarget=ios-source \
+            -Dcodename1.arg.ios.interpHost=true \
+            -Dopen=false
+
+      - name: Import signing material
+        env:
+          CERT_P12: ${{ secrets.IOS_DIST_CERT_P12 }}
+          CERT_PASSWORD: ${{ secrets.IOS_DIST_CERT_PASSWORD }}
+          PROFILE: ${{ secrets.IOS_PROVISIONING_PROFILE }}
+        run: |
+          set -euo pipefail
+          keychain=build.keychain
+          security create-keychain -p actions "$keychain"
+          security default-keychain -s "$keychain"
+          security unlock-keychain -p actions "$keychain"
+          echo "$CERT_P12" | base64 -d > cert.p12
+          security import cert.p12 -k "$keychain" -P "$CERT_PASSWORD" \
+            -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple: -s -k actions "$keychain"
+          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
+          echo "$PROFILE" | base64 -d > \
+            ~/Library/MobileDevice/Provisioning\ Profiles/devruntime.mobileprovision
+
+      - name: Archive and export
+        run: |
+          set -euo pipefail
+          src="$(find scripts/cn1-device-runtime/ios/target -maxdepth 1 \
+            -name '*-ios-source' -type d | head -1)"
+          [ -n "$src" ] || { echo "no Xcode project was generated" >&2; exit 1; }
+          cd "$src"
+          xcodebuild -workspace CN1DeviceRuntime.xcworkspace \
+            -scheme CN1DeviceRuntime -configuration Release \
+            -archivePath build/CN1DeviceRuntime.xcarchive archive
+          xcodebuild -exportArchive \
+            -archivePath build/CN1DeviceRuntime.xcarchive \
+            -exportPath build/ipa \
+            -exportOptionsPlist ../../store/ExportOptions.plist
+
+      - name: Upload to TestFlight
+        if: ${{ !inputs.dry_run }}
+        env:
+          ASC_ISSUER_ID: ${{ secrets.APPSTORE_ISSUER_ID }}
+          ASC_KEY_ID: ${{ secrets.APPSTORE_KEY_ID }}
+          ASC_PRIVATE_KEY: ${{ secrets.APPSTORE_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          mkdir -p ~/private_keys
+          echo "$ASC_PRIVATE_KEY" > ~/private_keys/AuthKey_$ASC_KEY_ID.p8
+          src="$(find scripts/cn1-device-runtime/ios/target -maxdepth 1 \
+            -name '*-ios-source' -type d | head -1)"
+          xcrun altool --upload-app -f "$src"/build/ipa/*.ipa -t ios \
+            --apiKey "$ASC_KEY_ID" --apiIssuer "$ASC_ISSUER_ID"

.gitignore

@@ -132,3 +132,6 @@ scripts/fidelity-app/common/src/main/resources/*ThemeDev.res
 # build time (common/pom.xml copy-native-themes); never commit the duplicate.
 scripts/fidelity-app/common/src/main/resources/iOSModernTheme.res
 scripts/fidelity-app/common/src/main/resources/AndroidMaterialTheme.res
+
+# Local Maven repository used for isolated local builds (see .m2-local)
+.m2-local/

CLAUDE.md

@@ -199,6 +199,59 @@ mvn -B -DskipTests=true -f ../vm/ByteCodeTranslator/pom.xml verify
 
 Findings land in each module's `target/spotbugsXml.xml`.
 
+### Device runtime (on-device interpreter)
+
+`scripts/hellocodenameone/` is a device runtime: an app that runs Codename One
+programs pushed from a desktop, interpreted rather than compiled. See
+`docs/developer-guide/Device-Runtime.asciidoc`. Verify on both platforms --
+`scripts/run-device-runtime-android.sh <Program.java>` (minutes) and
+`scripts/run-device-runtime-ios.sh <Program.java>` (~30 min).
+
+- **A pushed `main` runs on the EDT**, like an app's `start()`. `callSerially`
+  is legal there, `callSeriallyAndWait` is not.
+- **The EDT budget is per entry into the interpreter, not per session.** Every
+  framework callback is a fresh entry. Measuring from the start of the run makes
+  the budget expire once and stay expired, killing every later callback -- i.e.
+  every button press -- with "ran without yielding".
+- **Lambdas and method references are desugared** by `InterpLambdaDesugar` when
+  the bundle is written; neither target can spin a class at run time. String
+  concatenation needs `-XDstringConcat=inline` (cn1-push.sh passes it).
+- **A linker must dispatch on the receiver's class, not the call site's owner.**
+  `list.add(x)` compiles to a call naming `java.util.List`; resolving from there
+  finds `AbstractList.add`, whose body throws `UnsupportedOperationException`.
+  Android got this free from reflection; iOS resolves the receiver's class id
+  and walks up from there.
+- **`synchronized` uses the real host monitor**, so it interoperates with the
+  framework and `wait`/`notify` work. A synchronized method wraps the call (on
+  the peer where there is one); a synchronized block runs its region nested
+  inside a real `synchronized`, and `monitorexit` returns to the enclosing
+  level, which is what releases it.
+- **A pushed tree's non-`.java` files become resources**, published to
+  `CodenameOneImplementation` -- not `Display`, which `Resources.openLayered`
+  never passes through.
+- **`java.lang.Enum` has no shim and needs none** -- the interpreter answers
+  name/ordinal/valueOf itself, since Java forbids naming Enum as a superclass.
+- **The device dials out; the desktop listens.** A listening socket inside the
+  iOS simulator is unreachable from the host. Android needs `adb reverse`, not
+  `adb forward`. Both runtimes dial the same host port, so a running emulator
+  app will answer a push meant for the simulator -- the iOS script force-stops
+  it for exactly this reason.
+- **Push a source tree, not a file**: `scripts/cn1-push.sh src/main/java 18234`.
+  The entry point is discovered -- a `main`, else a `Lifecycle` subclass, which
+  is what a real app has. `scripts/devruntime-probes/` holds the battery of
+  programs that found the defects worth knowing about; run it after touching
+  the interpreter, the linkers or the shims.
+- **Regenerate shims with `scripts/generate-interp-shims.sh`** after changing
+  `GenerateInterpShims`. They are checked in on purpose. The script fails if a
+  shim will not compile (never prune -- that once ate `Interp_ui_Form`), if a
+  load-bearing shim is missing, or if generation is not reproducible.
+- **The generator reads the device's `java.*` from the `codenameone-java-runtime`
+  jar with ASM, not by reflecting over the JDK**, and runs under `JAVA17_HOME`.
+  The two disagree about which methods exist, which are `final`, which
+  interfaces a class implements, and which constructors exist. Note `javap`
+  resolves `java.*` from the platform even with `-cp`, so inspect the extracted
+  `.class` file directly or you will be reading the JDK's copy.
+
 ### Never rely on ClassCastException
 
 **ParparVM's `CHECKCAST` is unchecked.** `BC_CHECKCAST` expands to nothing and the

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

@@ -4544,12 +4544,59 @@ private int scanBackFirst(char[] chars, int ixStart, int ixEnd) {
     ///
     /// input stream for the resource or null if not found
     public InputStream getResourceAsStream(Class cls, String resource) {
+        InputStream local = localResource(resource);
+        if (local != null) {
+            return local;
+        }
         if (cls != null) {
             return cls.getResourceAsStream(resource);
         }
         return CodenameOneImplementation.class.getResourceAsStream(resource);
     }
 
+    /// Resources supplied at run time rather than compiled into the app.
+    ///
+    /// The device runtime pushes a program's own `theme.res`, CSS and images
+    /// here. They have to be visible from this layer rather than from
+    /// `Display`, because the calls that matter never pass through `Display`:
+    /// `Resources.openLayered("/theme")` and `UIManager.initFirstTheme` resolve
+    /// inside the framework, which asks the implementation directly.
+    ///
+    /// Empty in an ordinary app, and one emptiness check on a path that
+    /// already touches the file system. Allocated eagerly rather than lazily:
+    /// a push arrives on a socket thread while the event thread may be reading,
+    /// and lazily creating a shared static under that is how entries go missing.
+    private static final java.util.Hashtable localResources = new java.util.Hashtable();
+
+    /// Publishes a resource under the path an application would load it by,
+    /// e.g. `/theme.res`. A null value removes it.
+    public static void setLocalResource(String path, byte[] data) {
+        if (data == null) {
+            localResources.remove(path);
+        } else {
+            localResources.put(path, data);
+        }
+    }
+
+    /// Drops every published resource, so a newly pushed program does not
+    /// inherit the previous one's theme.
+    public static void clearLocalResources() {
+        localResources.clear();
+    }
+
+    /// A published resource as a stream, or null. Platform implementations call
+    /// this before falling back to the classpath.
+    protected static InputStream localResource(String resource) {
+        if (resource == null || localResources.isEmpty()) {
+            return null;
+        }
+        byte[] data = (byte[])localResources.get(resource);
+        if (data == null && !resource.startsWith("/")) {
+            data = (byte[])localResources.get("/" + resource);
+        }
+        return data == null ? null : new java.io.ByteArrayInputStream(data);
+    }
+
     /// Animations should return true to allow the native image animation to update
     ///
     /// #### Parameters

CodenameOne/src/com/codename1/interp/InterpBacked.java

@@ -0,0 +1,37 @@
+/*
+ * 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.codename1.interp;
+
+/// Implemented by a generated shim: a framework subclass standing in for an
+/// interpreted class.
+///
+/// Lets the runtime recover the interpreted object from the host-visible peer,
+/// which is what makes the round trip work -- interpreted code hands its peer
+/// to the framework, the framework hands the peer back to a listener, and the
+/// runtime has to get from there to the interpreted instance again.
+///
+/// @author Shai Almog
+public interface InterpBacked {
+    /// The interpreted object this peer stands for.
+    InterpObject getInterpObject();
+}