flet-box 1.0.3 → 1.0.5

package/docs/guides/mobile-and-platforms.md

@@ -0,0 +1,439 @@
+# Build FletBox for mobile and other platforms
+
+> **Level: Advanced.** This page is for shipping — skip it on a first read. It follows [minification and protection](minification-and-protection.md) in the book's reading path.
+
+FletBox applications can be built for the web and then packaged for mobile with Capacitor. The same frontend code can become a website, PWA, Android app, or iOS app.
+
+## The general flow
+
+```text
+FletBox source
+     |
+     | npm run build
+     v
+Web build / dist
+     |
+     | Capacitor sync
+     v
+Android project       iOS project
+     |                     |
+ APK / AAB              App Store app
+```
+
+Capacitor packages the compiled web application inside a native shell. You can add native Capacitor plugins later when the app needs device features.
+
+## Requirements
+
+### For every platform
+
+- Node.js 18 or newer.
+- npm.
+- A working FletBox project.
+- A production build that creates the directory configured as Capacitor's `webDir`.
+
+### For Android
+
+- Android Studio.
+- Android SDK.
+- Java/JDK compatible with the Android Gradle project.
+- An emulator or physical Android device for testing.
+
+### For iOS
+
+- macOS.
+- Xcode.
+- CocoaPods when required by installed plugins.
+- An Apple developer account for device distribution and App Store publishing.
+
+## Prepare the web build
+
+From the FletBox project:
+
+```bash
+npm install
+npm run build
+```
+
+Check that the build output exists before syncing Capacitor:
+
+```text
+dist/
+├── index.html
+└── src/
+    └── app.js
+```
+
+Your Capacitor configuration must point `webDir` to that output directory, commonly `dist`:
+
+```json
+{
+  "appId": "com.example.myapp",
+  "appName": "My FletBox App",
+  "webDir": "dist"
+}
+```
+
+The exact configuration file may be `capacitor.config.ts`, `capacitor.config.json`, or another format depending on how Capacitor was initialized.
+
+## Install Capacitor
+
+```bash
+npm install @capacitor/core @capacitor/cli
+```
+
+Initialize Capacitor:
+
+```bash
+npx cap init
+```
+
+The command asks for:
+
+- App name.
+- App package id, such as `com.example.myapp`.
+- Web output directory.
+
+Use a stable package id. Changing it later can create a different application in app stores.
+
+## Android
+
+Projects created with `flet-box create` already include Capacitor's Android
+configuration and commands for adding the platform, building the web assets,
+and generating launcher icons from `assets/logo.png`. See the [CLI Android
+workflow](../cli/README.md#create-an-android-app).
+
+To build a debug APK from one of these generated projects, run
+`flet-box build android`. It initializes the Android platform on first use,
+synchronizes the web assets and launcher icons, and compiles the APK.
+It installs missing npm project dependencies and prints the absolute APK path.
+Android Studio, Java, and the Android SDK remain system prerequisites and must
+be installed separately.
+
+### Add Android to the project
+
+```bash
+npm install @capacitor/android
+npx cap add android
+npx cap sync android
+```
+
+Run the web build before each sync when frontend files changed:
+
+```bash
+npm run build
+npx cap sync android
+```
+
+### Open Android Studio
+
+```bash
+npx cap open android
+```
+
+If Android Studio is installed in a custom location on macOS:
+
+```bash
+export CAPACITOR_ANDROID_STUDIO_PATH="/Applications/Android Studio.app"
+npx cap open android
+```
+
+Remove the custom override when it is no longer needed:
+
+```bash
+unset CAPACITOR_ANDROID_STUDIO_PATH
+```
+
+### Run on an emulator or device
+
+You can open the project in Android Studio and use the Run button, or use Capacitor's command when a device is configured:
+
+```bash
+npx cap run android
+```
+
+For a physical device, enable developer mode and USB debugging on the device.
+
+### Build a debug APK
+
+From the project root:
+
+```bash
+npm run build
+npx cap sync android
+cd android
+./gradlew assembleDebug --warning-mode all
+```
+
+On macOS, the generated debug APK is normally located at:
+
+```text
+android/app/build/outputs/apk/debug/app-debug.apk
+```
+
+The debug APK is for local testing and should not be published as the production release.
+
+### Build a release APK
+
+```bash
+cd android
+./gradlew assembleRelease
+```
+
+A release build must be signed before distribution. Configure a release signing key in the Android project and keep the keystore outside source control.
+
+### Build an Android App Bundle
+
+Google Play normally expects an Android App Bundle:
+
+```bash
+cd android
+./gradlew bundleRelease
+```
+
+The output is normally located at:
+
+```text
+android/app/build/outputs/bundle/release/app-release.aab
+```
+
+## iOS
+
+Projects created with `flet-box create` include Capacitor's iOS platform and
+scripts. On macOS, install the full Xcode app, an iOS simulator runtime, and
+CocoaPods (`sudo gem install cocoapods` and `pod setup`). Then run
+`flet-box build ios` to initialize the platform on first use, synchronize the
+web assets, regenerate the app icon, launch images and launch screen from
+`assets/logo.png`, and build an iOS Simulator `.app`. The command prints the
+absolute app path, normally
+`ios/build/Build/Products/Debug-iphonesimulator/App.app`, which installs with
+`xcrun simctl install booted <path>`.
+
+For real devices, `flet-box build ios --archive` writes
+`ios/build/App.xcarchive` for the `iphoneos` SDK. The archive is unsigned: open
+it in Xcode with a signing team to export an IPA.
+
+The Command Line Tools are not enough. `xcodebuild` is only a stub there and
+there is no simulator runtime, so the build command refuses to start and prints
+the `xcode-select -s /Applications/Xcode.app/Contents/Developer` fix instead of
+failing later inside Xcode. CocoaPods is checked too, because Capacitor links
+its native layer with Pods.
+
+### Capacitor origin
+
+Both platforms serve the app from a local HTTPS origin
+(`https://localhost`), configured with `androidScheme` and `iosScheme` in
+`capacitor.config.json`. A remote API has to allow that origin in its CORS
+configuration.
+
+### Add iOS to the project
+
+```bash
+npm install @capacitor/ios
+npx cap add ios
+npx cap sync ios
+```
+
+After frontend changes:
+
+```bash
+npm run build
+npx cap sync ios
+```
+
+### Open Xcode
+
+```bash
+npx cap open ios
+```
+
+Select a simulator or connected device in Xcode, configure the signing team, and run the application.
+
+For App Store distribution, configure:
+
+- Bundle identifier.
+- Signing team.
+- Development and distribution certificates.
+- Provisioning profile.
+- App icons and launch assets.
+- Privacy descriptions for any native plugins.
+
+## Capacitor assets
+
+Install the asset helper:
+
+```bash
+npm install -D @capacitor/assets
+```
+
+Prepare source icons according to the Capacitor assets requirements, then generate platform assets with the relevant Capacitor assets command for your project version.
+
+Review the generated icons in Android Studio and Xcode before publishing.
+
+## Update Capacitor
+
+Update the core packages together:
+
+```bash
+npm install @capacitor/core@latest @capacitor/cli@latest @capacitor/android@latest
+```
+
+For iOS projects, include the iOS package too:
+
+```bash
+npm install @capacitor/ios@latest
+```
+
+Then synchronize native projects:
+
+```bash
+npx cap sync android
+npx cap sync ios
+```
+
+Read the Capacitor migration notes before updating a major version.
+
+## macOS permission fixes
+
+If Gradle cannot execute on macOS:
+
+```bash
+cd android
+chmod +x gradlew
+xattr -c gradlew
+```
+
+Then retry:
+
+```bash
+./gradlew assembleDebug --warning-mode all
+```
+
+`chmod` makes the script executable. `xattr -c` removes macOS quarantine metadata from that local script. Only do this for project files you trust.
+
+## PWA alternative
+
+A FletBox app can also be installed as a Progressive Web App without Capacitor:
+
+```javascript
+import { installPWA, isPWAInstalled } from "flet-box";
+
+if (!isPWAInstalled()) {
+  installPWA();
+}
+```
+
+A PWA needs:
+
+- A valid web manifest.
+- A registered service worker.
+- HTTPS in production, except for localhost.
+- Icons in the expected sizes.
+
+PWA installation depends on browser and platform support.
+
+## Desktop options
+
+Capacitor targets Android and iOS. For desktop packaging, consider a desktop shell such as Electron or Tauri around the same `dist` output.
+
+The general idea remains:
+
+```text
+npm run build
+package dist with the desktop tool
+```
+
+Desktop packaging requires its own application configuration, signing, and distribution process.
+
+## Updating the app after code changes
+
+Use this cycle:
+
+```bash
+npm run build
+npx cap sync android
+npx cap open android
+```
+
+For iOS, replace the Android command:
+
+```bash
+npm run build
+npx cap sync ios
+npx cap open ios
+```
+
+`cap sync` copies the current web build and updates native dependencies. It does not replace the need to rebuild the web application first.
+
+## Troubleshooting
+
+### Capacitor cannot find the web directory
+
+Check that:
+
+1. `npm run build` completed successfully.
+2. The output directory exists.
+3. `webDir` points to that directory.
+
+### Android Studio does not open
+
+Set the path temporarily:
+
+```bash
+export CAPACITOR_ANDROID_STUDIO_PATH="/Applications/Android Studio.app"
+npx cap open android
+```
+
+### Gradle says permission denied
+
+```bash
+cd android
+chmod +x gradlew
+xattr -c gradlew
+```
+
+### The native app shows an old version
+
+Rebuild and synchronize:
+
+```bash
+npm run build
+npx cap sync android
+```
+
+Then rebuild from Android Studio or Gradle.
+
+### The APK installs but the screen is blank
+
+Check:
+
+- The `webDir` configuration.
+- That `dist/index.html` exists.
+- That asset paths work from the packaged app.
+- Browser console logs through Android Studio or Safari Web Inspector.
+- That the app does not depend on a development server URL.
+
+### The app works in the browser but not on the device
+
+Check absolute URLs, CORS, secure connections, permissions, and native plugin configuration. A mobile WebView is not identical to a desktop browser.
+
+## Release checklist
+
+- Build from a clean working tree.
+- Update the app version.
+- Run `npm run build`.
+- Run `npx cap sync`.
+- Test on a real device.
+- Verify icons, splash screen, orientation, and deep links.
+- Configure release signing.
+- Remove development URLs and debug credentials.
+- Confirm API endpoints use HTTPS.
+- Generate an APK for direct testing or an AAB for Google Play.
+- Keep signing keys and certificates out of Git.
+
+---
+
+## Continue reading
+
+- **Previous:** [Minify and protect a FletBox build](minification-and-protection.md)
+- **Next:** [Compatibility and support](compatibility.md) — Appendix C
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/online-updates.md

@@ -0,0 +1,196 @@
+# Ship updates without the store (OTA / online updates)
+
+> **Level: Advanced.** This page is for shipping — skip it on a first read. It follows [Add FletBox to an existing page](embedding.md) in the book's reading path.
+
+FletBox apps are 100% web at their core: the Android/iOS build is a thin native shell (Capacitor) around a web bundle. That means the **web layer can update itself over the air**: you publish the app to the store **once**, and every later change to your UI/logic reaches installed apps the next time they open — no new store submission, no user download of the whole app.
+
+This page explains the whole pipeline: what `flet-box release` does, what the `config.json` manifest contains, what the running app does with it, and — critically — **what OTA can and cannot change**.
+
+## The pipeline at a glance
+
+```text
+you edit source code
+        |
+        | flet-box release          (bumps version, rebuilds www/, git tag v1.0.1)
+        v
+git tag v1.0.1 pushed to GitHub
+        |
+        | GitHub Actions (on: tags v*)
+        v
+www/ deployed to GitHub Pages      <- the ONLY place an update is published
+        |
+        | app opens (web or installed mobile app)
+        v
+loader.js fetches <update.url>/config.json
+        |
+        | hash differs from the running bundle?
+        +-- no  -> run the bundle already on the device
+        +-- yes -> show "Update available" dialog
+                     |  Accept
+                     v
+                   download bundle, verify sha256, store it, run it
+```
+
+Three invariants make this safe:
+
+1. **Updates are published only by release tags.** Ordinary `git push` runs CI (so breakage is caught) but never publishes, so a half-finished test build can never reach your users.
+2. **The app verifies integrity.** A downloaded bundle is executed only if its sha256 matches the hash in `config.json`.
+3. **The app always launches.** Offline, a wrong URL, a hash mismatch, or a declined dialog all fall back to the bundle already on the device. OTA can never brick the app.
+
+## Cutting a release
+
+Work on your code freely and build preview bundles as often as you like — **the version number does not move** on a normal build. When the code is stable and you want it to reach users:
+
+```bash
+flet-box release            # bump PATCH  (1.0.0 -> 1.0.1), rebuild, commit, tag v1.0.1
+flet-box release --minor    # bump MINOR  (1.0.0 -> 1.1.0)
+flet-box release --major    # bump MAJOR  (1.0.0 -> 2.0.0)
+flet-box release --push     # also push the commit and the tag to origin
+```
+
+`flet-box release` does, in order:
+
+1. Refuses to run if the working tree has uncommitted changes (the tag must capture exactly what you release).
+2. Bumps the version in `package.json` using the odometer scheme below.
+3. Rebuilds the production bundle (`www/`), which regenerates `www/config.json` with the new version and the sha256 of the new bundle.
+4. Commits the version bump and creates the annotated tag `vX.Y.Z`.
+5. Optionally pushes (`--push`), which triggers the CI deploy.
+
+If the build fails, the version bump is rolled back so a failed release leaves no trace.
+
+### Odometer versioning
+
+Versions are `MAJOR.MINOR.PATCH` where **MAJOR grows without bound** and **MINOR/PATCH are single digits (0–9)** that carry like an odometer:
+
+```text
+1.0.8 -> 1.0.9 -> 1.1.0 -> ... -> 1.9.9 -> 2.0.0 -> ... -> 9.9.9 -> 10.0.0
+```
+
+When a position passes 9 it resets to 0 and carries into the position on its left. MAJOR never caps, so you can never run out of versions.
+
+## The `config.json` manifest
+
+Every bundle ships a small manifest at `www/config.json`. This is what a running app fetches (a ~200-byte check, not the whole bundle):
+
+```json
+{
+  "version": "1.0.1",
+  "hash": "494ca992aecf2de1e32680eae56405ec42baaa9b455248a4999df2edb76ad0b9",
+  "builtAt": "2026-10-11T19:53:24.524Z",
+  "bundle": "src/app.js",
+  "size": 36132,
+  "minNativeVersion": "0.0.0",
+  "update": {
+    "url": "https://kuko53348.github.io/my-app/",
+    "mode": "prompt",
+    "channel": "stable",
+    "mandatory": false,
+    "notes": "Fixed the login timeout."
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `version` | Human-readable label from `package.json` (shown in the dialog). |
+| `hash` | sha256 of the bundle. **This is what drives the update decision**, not the version. |
+| `bundle` | Path of the bundle relative to the update URL. |
+| `size` | Bundle size in bytes (shown in the dialog as KB). |
+| `minNativeVersion` | Oldest native shell this bundle supports. Older shells are told to update from the store instead. |
+| `update.url` | Where `config.json` and the bundle are published (your GitHub Pages site). |
+| `update.mode` | `prompt` (ask the user, default) or `auto` (download silently). |
+| `update.mandatory` | `true` hides the "Later" button so the update cannot be skipped. |
+| `update.notes` | Release notes shown in the dialog. |
+| `update.channel` | Label for rollout channels (e.g. `stable`, `beta`). |
+
+### Where the update URL comes from
+
+`update.url` is resolved automatically, in this order:
+
+1. `update.url` in `fletbox.config.json` at your project root (explicit wins).
+2. Derived from the `repository` field of `package.json`, mapped to GitHub Pages: `https://<user>.github.io/<repo>/`.
+3. Derived from the **current project's** git remote `origin` (when it is a GitHub URL). This means `flet-box createBundle` always points at the project it is built in, never at the flet-box framework installed as a dependency.
+4. If none of these exist, OTA is **disabled** and the bundle simply runs what shipped in it.
+
+To configure it by hand, create `fletbox.config.json`:
+
+```json
+{
+  "update": {
+    "url": "https://kuko53348.github.io/my-app/",
+    "mode": "prompt",
+    "mandatory": false,
+    "notes": "",
+    "minNativeVersion": "0.0.0",
+    "channel": "stable"
+  }
+}
+```
+
+## What the app does on launch
+
+`www/loader.js` (wired in automatically as the module entry of every production bundle) runs **before** your app:
+
+1. Reads the shipped `config.json` to learn the update URL and the hash of the bundle on the device.
+2. Fetches the remote `config.json` with `cache: no-store` and a short timeout.
+3. If the remote hash equals the running hash, it logs "up to date" and starts the app immediately.
+4. If they differ, it either downloads silently (`mode: "auto"` or `mandatory`) or shows the **Update available** dialog with the version change, your release notes, and the download size, offering **Later** / **Update now**.
+5. On accept it downloads the bundle, recomputes its sha256, and only runs it if the hash matches. The bundle is then kept in Cache Storage so the next launch uses it even offline.
+
+The dialog is plain HTML/CSS rendered by the loader itself, so it appears before the framework (and your UI) loads.
+
+## What OTA can and cannot change
+
+OTA replaces the **web layer only** — the files inside `www/`.
+
+| Updates over the air | Needs a new store submission |
+| --- | --- |
+| UI, screens, widgets, styles | New native plugins / Capacitor version |
+| App logic and routing | New Android/iOS permissions |
+| Text, images, fonts, assets in `www/` | Changes to `AndroidManifest.xml` / `Info.plist` |
+| Bug fixes and new JS features | Native code or signing changes |
+| Anything inside the bundle | Anything that changes the app's identity or purpose |
+
+Rule of thumb: if the change lives in `src/` (your FletBox code) it ships OTA; if it lives in the native shell it goes through the store. The `minNativeVersion` field exists for the boundary case where a new web bundle needs a newer shell: older shells skip the OTA and you direct users to the store update.
+
+## Store policy (read this before relying on OTA)
+
+Both stores permit over-the-air updates of **interpreted code** (JavaScript in a WebView counts), with conditions. This is a summary, not legal advice — check the current policy text before shipping.
+
+- **Google Play** (Device and Network Abuse policy): apps may not download and execute code that changes the app's behavior outside a virtual machine/interpreter. Code running in an interpreter (your JS in the Capacitor WebView) **is** allowed. You may add features and fix bugs OTA; you may not push new APKs or escalate permissions OTA.
+- **Apple (App Review Guideline 2.5.2)**: interpreted code may be updated OTA only if it does not change the **primary purpose** of the app. Patches, minor features, and assets are fine; turning a catalog app into a payment app (or anything that changes what the app fundamentally is) requires review.
+
+Because of these rules, keep OTA updates within the app's existing purpose, and never use OTA to request new permissions or swap the native shell.
+
+## Offline behaviour and the service worker
+
+The generated service worker uses a hybrid strategy so OTA and offline coexist:
+
+- **Updatable shell** (`index.html`, `loader.js`, `config.json`, `src/app.js`): network-first. Online users always get fresh bytes, so a new release is picked up immediately and the worker never serves a stale `app.js`. Offline, the last cached copy is used.
+- **Static assets** (fonts, icons, images, css): cache-first, since they are immutable per release.
+- **Cross-origin requests** (your remote `config.json` and bundle) are left to the network and are never cached by the worker.
+
+Downloaded OTA bundles live in a **separate** cache (`fletbox-ota`) owned by the loader, so a service-worker update never wipes an installed OTA bundle.
+
+## Requirements and troubleshooting
+
+Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings → Pages → Source = "GitHub Actions"), and the workflow from `flet-box create` (it already deploys `www/` on `v*` tags). GitHub Pages and Actions are free for public repos.
+
+| Symptom | Likely cause |
+| --- | --- |
+| Build prints "THIS APP DOES NOT SUPPORT OTA UPDATES" | No public GitHub repo is reachable from the project (no `origin` remote, a non-GitHub remote, or nothing configured). The app still works — it runs the bundle it shipped with. Create the repo, push it, and rebuild. |
+| No dialog, app runs old code | `update.url` missing/incorrect, or the tag was never pushed (CI never published). |
+| `hash mismatch` in console | The published `config.json` and bundle are from different builds. Re-run `flet-box release` so both are published together. |
+| Dialog appears but download fails | The Pages site is not reachable/CORS-blocked from the app origin. Pages serves with permissive headers; check you are not behind a proxy that strips them. |
+| Update applies but reverts on next launch | Cache Storage unavailable (private browsing). The bundle runs once but cannot persist. |
+| Want to force a clean state | Clear site data for the app origin (this removes the OTA cache and localStorage entry). |
+
+Because the decision is hash-based, two builds of identical source produce the same hash and no spurious update is offered; only a real content change triggers the dialog.
+
+---
+
+## Continue reading
+
+- **Previous:** [Add FletBox to an existing page](embedding.md)
+- **Next:** none — you reached the end of the book.
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)