[DO NOT MERGE] Merge apps into main

.eslintrc.cjs

@@ -21,6 +21,9 @@ module.exports = {
     "bootstrap-template.js",
     "playwright.config.ts",
     "CMakeFiles",
+    "android",
+    "ios",
+    "firmware",
   ],
   parser: "@typescript-eslint/parser",
   parserOptions: {

.github/workflows/android-build.yml

@@ -0,0 +1,105 @@
+name: Android Build
+
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - "**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ startsWith(github.ref, 'refs/tags/v') && 'release' || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+
+jobs:
+  build-android:
+    # Only run for apps releases, not web releases
+    if: ${{ github.event_name != 'release' || contains(github.event.release.tag_name, '-apps') }}
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          registry-url: "https://npm.pkg.github.com"
+
+      - uses: microbit-foundation/npm-package-versioner-action@v1
+
+      # Strip prerelease suffix - app stores require X.Y.Z format
+      - name: Set marketing version
+        run: echo "MARKETING_VERSION=$(jq -r .version package.json | sed 's/-.*//')" >> $GITHUB_ENV
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "21"
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: echo "ML_THEME_VERSION=$(jq -r '.["theme-package-version"]' workflow-config.json)" >> $GITHUB_ENV
+
+      - run: npm install --no-save @microbit-foundation/ml-trainer-microbit@${{ env.ML_THEME_VERSION }}
+        if: github.repository_owner == 'microbit-foundation'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: npm run build:apps
+
+      - run: npx cap sync android
+
+      - name: Decode keystore
+        run: |
+          echo "SIGNING_STORE_FILE=$RUNNER_TEMP/keystore.jks" >> $GITHUB_ENV
+          printenv SIGNING_STORE_FILE_BASE64 | base64 -d > "$RUNNER_TEMP/keystore.jks"
+        env:
+          SIGNING_STORE_FILE_BASE64: ${{ secrets.ANDROID_SIGNING_STORE_FILE_BASE64 }}
+
+      - name: Build with Fastlane
+        run: bundle exec fastlane android build
+        env:
+          SIGNING_KEY_ALIAS: upload
+          SIGNING_KEY_PASSWORD: ${{ secrets.ANDROID_SIGNING_PASSWORD }}
+          SIGNING_STORE_PASSWORD: ${{ secrets.ANDROID_SIGNING_PASSWORD }}
+          BUILD_NUMBER: ${{ github.run_number }}
+          MARKETING_VERSION: ${{ env.MARKETING_VERSION }}
+
+      - name: Clean up keystore
+        run: rm -f "$RUNNER_TEMP/keystore.jks"
+        if: always()
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: android-apk-${{ github.sha }}
+          path: android/app/build/outputs/apk/release/*.apk
+          retention-days: 30
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: android-aab-${{ github.sha }}
+          path: android/app/build/outputs/bundle/release/*.aab
+          retention-days: 30
+
+      - name: Authenticate to Google Cloud
+        if: github.event_name == 'release'
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: projects/311821962964/locations/global/workloadIdentityPools/github-actions-pool/providers/github-actions
+          service_account: fastlane-supply@microbit-fastlane.iam.gserviceaccount.com
+
+      - name: Upload to Google Play
+        if: github.event_name == 'release'
+        run: bundle exec fastlane android upload

.github/workflows/build.yml

@@ -13,6 +13,8 @@ concurrency:
 
 jobs:
   build:
+    # Skip apps releases - handled by ios-build.yml and android-build.yml
+    if: ${{ github.event_name != 'release' || !contains(github.event.release.tag_name, '-apps') }}
     timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
@@ -32,22 +34,24 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: 20
+          node-version: 24
           cache: "npm"
           registry-url: "https://npm.pkg.github.com"
       - uses: microbit-foundation/npm-package-versioner-action@v1
       - run: npm ci
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: npm install --no-save @microbit-foundation/ml-trainer-microbit@0.2.0-dev.78 @microbit-foundation/website-deploy-aws@0.6 @microbit-foundation/website-deploy-aws-config@0.10
+      - run: echo "ML_THEME_VERSION=$(jq -r '.["theme-package-version"]' workflow-config.json)" >> $GITHUB_ENV
+      - run: npm install --no-save @microbit-foundation/ml-trainer-microbit@${{ env.ML_THEME_VERSION }} @microbit-foundation/website-deploy-aws@0.6 @microbit-foundation/website-deploy-aws-config@0.10
         if: github.repository_owner == 'microbit-foundation'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - run: node ./bin/print-ci-env.cjs >> $GITHUB_ENV
       - run: npm run ci
       - name: Run Playwright tests
         if: env.STAGE == 'REVIEW' || env.STAGE == 'STAGING' || env.STAGE == 'BETA'
-        uses: docker://mcr.microsoft.com/playwright:v1.45.0-jammy
+        uses: docker://mcr.microsoft.com/playwright:v1.58.2-jammy
         with:
           args: npx playwright test
       - name: Store reports

.github/workflows/ios-build.yml

@@ -0,0 +1,89 @@
+name: iOS Build
+
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - "**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ startsWith(github.ref, 'refs/tags/v') && 'release' || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+
+jobs:
+  build-ios:
+    # Only run for apps releases, not web releases
+    if: ${{ github.event_name != 'release' || contains(github.event.release.tag_name, '-apps') }}
+    timeout-minutes: 25
+    runs-on: macos-26
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          registry-url: "https://npm.pkg.github.com"
+
+      - uses: microbit-foundation/npm-package-versioner-action@v1
+
+      # Strip prerelease suffix - app stores require X.Y.Z format
+      - name: Set marketing version
+        run: echo "MARKETING_VERSION=$(jq -r .version package.json | sed 's/-.*//')" >> $GITHUB_ENV
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Setup SSH for Match
+        run: |
+          eval "$(ssh-agent -s)"
+          echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> $GITHUB_ENV
+          echo "SSH_AGENT_PID=$SSH_AGENT_PID" >> $GITHUB_ENV
+          ssh-add - <<< "$FASTLANE_MATCH_DEPLOY_KEY"
+        env:
+          FASTLANE_MATCH_DEPLOY_KEY: ${{ secrets.FASTLANE_MATCH_DEPLOY_KEY }}
+
+      - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: echo "ML_THEME_VERSION=$(jq -r '.["theme-package-version"]' workflow-config.json)" >> $GITHUB_ENV
+
+      - run: npm install --no-save @microbit-foundation/ml-trainer-microbit@${{ env.ML_THEME_VERSION }}
+        if: github.repository_owner == 'microbit-foundation'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: npm run build:apps
+
+      - run: npx cap sync ios
+
+      - run: pod install
+        working-directory: ios/App
+
+      - name: Build with Fastlane
+        run: bundle exec fastlane ios build
+        env:
+          MATCH_PASSWORD: ${{ secrets.FASTLANE_MATCH_PASSWORD }}
+          BUILD_NUMBER: ${{ github.run_number }}
+          MARKETING_VERSION: ${{ env.MARKETING_VERSION }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ios-app-${{ github.sha }}
+          path: ios/App/build/output/*.ipa
+          retention-days: 30
+
+      - name: Upload to TestFlight
+        if: github.event_name == 'release'
+        run: bundle exec fastlane ios upload
+        env:
+          APP_STORE_CONNECT_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
+          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
+          APP_STORE_CONNECT_KEY_CONTENT: ${{ secrets.APP_STORE_CONNECT_KEY_CONTENT }}

.gitignore

@@ -1,5 +1,5 @@
 /dist/
-/.idea/
+.idea/
 /node_modules/
 
 .DS_Store
@@ -16,7 +16,17 @@
 
 .env.*
 
+/screenshots/
 /src/.DS_Store
 /playwright-report/
 /test-results/
-/ml4f-output/
+/ml4f-output/
+/android/app/src/main/assets/public
+/ios/App/App/public
+
+# Fastlane
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots
+fastlane/test_output
+Gemfile.lock

.prettierignore

@@ -1,2 +1,3 @@
 src/translations.ts
 src/messages/
+src/images/

AGENTS.md

@@ -0,0 +1,36 @@
+# AI agent notes
+
+## Formatting/style
+
+Run `npm run format` to format code with Prettier.
+
+New files should have a copyright header with the current year which is 2026. Use an existing file as a template but update the year.
+
+When documenting properties/fields use the following style of comment:
+
+```typescript
+/**
+ * Example comment text.
+ */
+```
+
+## Internationalization (i18n)
+
+To add or amend UI strings:
+
+1. Edit `lang/ui.en.json`
+2. Run `find lang -type f -not -name ui.en.json | while read n; do git checkout main -- $n; done  && npm run i18n:compile` to update `src/messages/` via formatjs and ensure that outdated text of new message is not preserved in translation bundles as we iterate on the text.
+
+## Vitest
+
+To run a subset of unit tests, pass a file pattern directly (not `--testPathPattern`):
+
+```bash
+npm test -- download-machine-browser-default
+```
+
+## Playwright
+
+If you run the e2e tests, be sure to run them headlessly via `npm run test:e2e:headless`.
+
+When updating `@playwright/test` in package.json, also update the Docker image version in `.github/workflows/build.yml` to match.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "fastlane"

README.md

@@ -48,6 +48,58 @@ See the section about [running tests](https://facebook.github.io/create-react-ap
 Builds the app for production to the `dist` folder.\
 It correctly bundles React in production mode and optimizes the build for the best performance.
 
+## iOS/Android development
+
+### Local development
+
+To get a proper dev server for iOS/Android development run:
+
+```bash
+npm run cap:sync:dev
+```
+
+Then run
+
+```bash
+npm run dev:apps
+```
+
+Use e.g. `npx cap open ios` to open the IDE and run from there.
+
+The vite dev server run by dev:apps will be running inside the app.
+
+### Signed builds
+
+CI builds signed artifacts using [Fastlane](https://fastlane.tools/). iOS certificates and provisioning profiles are managed via [Fastlane Match](https://docs.fastlane.tools/actions/match/) with encrypted credentials stored in a private repository. Android signing uses a keystore stored in CI secrets.
+
+To run Fastlane locally:
+
+```bash
+bundle install
+bundle exec fastlane ios build    # Build signed IPA (macOS only)
+bundle exec fastlane android build # Build signed APK/AAB
+```
+
+Or you can use Homebrew via `brew install fastlane` and drop the `bundle exec` (this can sidestep Ruby version issues).
+
+Android builds require the signing keystore and passwords via environment variables. iOS builds require Match credentials to fetch certificates.
+
+### App versioning
+
+App releases use tags with an `-apps` suffix to distinguish them from web releases on main until we merge the apps work back. The marketing version is derived from the tag with the suffix stripped (store limitation).
+
+When creating an apps tag we target next unreleased minor version, so if main is on v1.2.3:
+
+| Stage    | Example tag              | Marketing version | Build number  |
+| -------- | ------------------------ | ----------------- | ------------- |
+| Internal | `v1.3.0-apps.internal.1` | 1.3.0             | CI run number |
+| Beta     | `v1.3.0-apps.beta.1`     | 1.3.0             | CI run number |
+| Public   | `v1.3.0-apps`            | 1.3.0             | CI run number |
+
+If main releases a new minor version (e.g., 1.3.0) before apps ships, then we'll bump the next apps version (assuming we've merged main into apps).
+
+If we've merged apps back into main before we get to a public release we can drop the apps suffix.
+
 ## Deployments
 
 Most users should use the supported Foundation deployment at https://createai.microbit.org/