lecodes-cli 2.4.1 → 2.4.3

package/src/commands/app/templates/android.ts

@@ -1,3 +1,5 @@
+import type { AppLink } from "../shared"
+
 /* Templates for `lecodes app init android` / `lecodes app sync` — the Android mirror of
  * ios.ts, distilled from the LetaryCreatorViewer host (lecodes-android :app). The
  * same three ownership tiers: app/ is USER-owned after generation (init writes once, sync
@@ -155,6 +157,75 @@ export const runtimeManifestTemplate = (updateUrl: string | undefined): string =
 </manifest>
 `
 
+/** The window setup every shell's theme inherits (what Theme.LeCodesApp carried before the splash):
+ *  edge-to-edge bars, no title, and the window background — black, or app.json "splash"'s
+ *  layer-list. */
+const runtimeThemeItems = (windowBackground: string): string => `
+        <item name="android:windowTranslucentNavigation">true</item>
+        <item name="android:statusBarColor">@android:color/transparent</item>
+        <item name="android:windowNoTitle">true</item>
+        <item name="android:windowTranslucentStatus">true</item>
+        <item name="android:windowBackground">${windowBackground}</item>`
+
+/** What app.json "splash" resolved to, as the runtime module's resources need it (`size` = the side
+ *  of the square the image is fitted into, dp). */
+export interface AndroidSplashResources { backgroundHex: string, image: boolean, size: number }
+
+/** The Android 12+ splash-icon canvas (an icon without an icon background), dp — the system shows
+ *  its inner 192 dp circle. The image sits on it inset by (canvas − size) / 2. */
+export const SPLASH_ICON_CANVAS_DP = 288
+
+/** lecodes-runtime/src/main/res/values/lecodes_splash.xml — CLI-owned, written by init and every
+ *  sync: Theme.LeCodesRuntime, the parent of the app's user-owned Theme.LeCodesApp (themes.xml).
+ *  Without "splash" its window is black, as a shell's always was; with it, the colour and the
+ *  layer-list lecodes_splash_window (API 23–30 show the splash as the window background). The
+ *  parent needs appcompat on the module's classpath: SDK_RUNTIME_DEPS declares it. */
+export const runtimeThemeTemplate = (splash?: AndroidSplashResources): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` — regenerated on every sync, do not edit. Theme.LeCodesRuntime is
+     the parent of the app's Theme.LeCodesApp (app/src/main/res/values/themes.xml); app.json "splash"
+     draws its window. -->
+<resources>${splash ? `
+    <color name="lecodes_splash_background">${splash.backgroundHex}</color>` : ""}
+    <style name="Theme.LeCodesRuntime" parent="Theme.AppCompat.Light.NoActionBar">${runtimeThemeItems(splash ? "@drawable/lecodes_splash_window" : "@android:color/black")}
+    </style>
+</resources>
+`
+
+/** lecodes-runtime/src/main/res/values-v31/lecodes_splash.xml — only with app.json "splash": the
+ *  theme's Android 12+ twin (a v31 style replaces the base one whole, hence every item again) adding
+ *  the system splash — the colour, and as the icon the image inset (288 − size) / 2 dp on each side
+ *  (the 288 dp icon canvas with the image at its size, 160 dp by default) or nothing (transparent: the system would draw the launcher
+ *  icon otherwise). */
+export const runtimeThemeV31Template = (splash: AndroidSplashResources): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` from app.json "splash" — regenerated on every sync, do not edit. -->
+<resources>
+    <style name="Theme.LeCodesRuntime" parent="Theme.AppCompat.Light.NoActionBar">${runtimeThemeItems("@drawable/lecodes_splash_window")}
+        <item name="android:windowSplashScreenBackground">@color/lecodes_splash_background</item>
+        <item name="android:windowSplashScreenAnimatedIcon">${splash.image ? "@drawable/lecodes_splash_icon" : "@android:color/transparent"}</item>
+    </style>
+</resources>
+`
+
+/** lecodes-runtime/src/main/res/drawable/lecodes_splash_window.xml — the splash as a window
+ *  background: the colour, and the image centred at size × size dp (drawable-*dpi/lecodes_splash.png). */
+export const splashWindowTemplate = (splash: AndroidSplashResources): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` from app.json "splash" — regenerated on every sync, do not edit. -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android" android:opacity="opaque">
+    <item android:drawable="@color/lecodes_splash_background" />${splash.image ? `
+    <item android:width="${splash.size}dp" android:height="${splash.size}dp" android:gravity="center" android:drawable="@drawable/lecodes_splash" />` : ""}
+</layer-list>
+`
+
+/** lecodes-runtime/src/main/res/drawable/lecodes_splash_icon.xml — Android 12+'s splash icon: the
+ *  size dp image inset to the 288 dp canvas the system draws (and masks to a 192 dp circle). The
+ *  inset is rounded down — an odd size leaves the image half a dp larger, which nobody sees. */
+export const splashIconTemplate = (size: number): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` from app.json "splash" — regenerated on every sync, do not edit. -->
+<inset xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/lecodes_splash"
+    android:inset="${Math.floor((SPLASH_ICON_CANVAS_DP - size) / 2)}dp" />
+`
+
 /** lecodes-runtime/src/main/kotlin/io/letary/lecodes/runtime/LeCodesRuntime.kt — the generated
  *  registration + host-hook surface. Plugins are called by FQN (no import collisions); the
  *  activity hooks forward to the SDK's LeCodesAppHooks, which NAMES NO PLUGIN — a plugin that
@@ -259,7 +330,8 @@ lecodes app build android        # signed release .apk + .aab → ../dist/
 | \`app/\` (sources, manifest, res, build.gradle.kts, proguard-rules.pro) | **Yours** after init — sync never rewrites them (it only restamps the \`versionName\`/\`versionCode\` and \`isMinifyEnabled\`/\`isShrinkResources\` values, manages \`// lecodes:plugin\`-tagged lines in the plugins block, and — when \`app.json\` sets \`"icon"\` — the icon files below) |
 | \`app/src/main/assets/\` | CLI-owned — wiped and regenerated by every sync (the compiled \`app.js\` + its \`// preload:\` assets) |
 | \`res/mipmap-*/ic_launcher*\`, \`res/values/lecodes_icon.xml\` | CLI-owned **only when** \`app.json\` sets \`"icon"\` — regenerated by every sync (plus a value-only \`android:icon\` restamp in the manifest); without the key sync never touches icons |
-| \`settings.gradle.kts\`, \`build.gradle.kts\` (root), \`gradle.properties\`, \`lecodes-runtime/\`, \`plugins/\` | CLI-owned — regenerated by every sync |
+| \`app/src/main/res/values/themes.xml\` | **Yours** — its \`Theme.LeCodesApp\` must keep \`parent="Theme.LeCodesRuntime"\` (the window setup and the splash, see "Splash screen") |
+| \`settings.gradle.kts\`, \`build.gradle.kts\` (root), \`gradle.properties\`, \`lecodes-runtime/\`, \`plugins/\` | CLI-owned — regenerated by every sync (\`lecodes-runtime/src/main/res/\`: \`Theme.LeCodesRuntime\` and, when \`app.json\` sets \`"splash"\`, the splash resources) |
 | \`gradle/\`, \`gradlew\`, \`gradlew.bat\` | Written once at init |
 
 ## The SDK
@@ -346,23 +418,50 @@ Prefer hand-made icons? Leave \`"icon"\` unset and use Android Studio (right-cli
 New → Image Asset) — sync never touches icon files then. \`drawable/ic_launcher.xml\` is only
 the init-time placeholder.
 
+## Splash screen
+
+\`"splash": { "background": "#RRGGBB", "image": "./splash.png", "size": 160 }\` in \`../app.json\`
+(every key optional) makes every sync render the splash into \`lecodes-runtime/src/main/res/\`: the
+colour (\`background\`, default \`"iconBackground"\`, default white) with the image fitted centred into
+a \`size\`×\`size\` dp square (160 by default) — never at its pixel size — from
+\`drawable-mdpi…xxxhdpi/lecodes_splash.png\` (size × 1/1.5/2/3/4 px: 160…640 at the default) of the one
+master. Android 12+ shows it as the system splash (\`windowSplashScreenBackground\` +
+\`windowSplashScreenAnimatedIcon\`: the image on the 288 dp icon canvas, inset (288 − size) / 2 dp,
+of which the system shows only the inner 192 dp circle — keep the mark inside one; a \`size\` above
+192 is cut there, sync warns, and 288 is the most it takes), API 23–30 as the window background. Use
+a square mark of at least 3 × size px (a non-square one is fitted into the square, a smaller one is
+upscaled). No image = the colour
+alone (and no icon on Android 12+, not the launcher one). The app holds the splash until its first
+frame — through the first-launch wait of an OTA shell too.
+
+It reaches the app through the theme: \`Theme.LeCodesApp\` in \`app/src/main/res/values/themes.xml\`
+(yours) must say \`parent="Theme.LeCodesRuntime"\` and set no \`android:windowBackground\` of its
+own. A shell generated before the key existed does not — \`lecodes app sync\` and \`lecodes app
+doctor\` print the edit. Without the key the runtime theme keeps the black window shells always had.
+
 ## Notes
 
 
 ## Over-the-air updates
 
-Native, before the JS engine: \`LeCodesShell.boot(engine, context)\` in \`AppViewModel\` asks the
-source for newer code (a conditional GET; offline is a no-op), stores it and runs it on the NEXT
-launch — the current launch runs the newest LOCAL bundle. Configured in \`../app.json\`:
-\`"update": true\` = the project's live bundle on the platform (a pushed project), \`"update":
-{ "url": "https://…/app.js" }\` = your own hosting, \`false\` = off. Sync writes the URL into
+Native, before the JS engine: \`LeCodesShell.boot(engine, activity)\` in \`AppViewModel\` takes the
+newest LOCAL bundle, then asks the source for newer code (a conditional GET; offline is a no-op)
+and stores it. The FIRST launch of an installed binary waits for that answer (5 s at most, the
+splash held on screen) and runs the newest bundle at once, so a fresh install from the store never
+starts on the older code it shipped with; every later launch runs the local bundle at once and a
+download applies on the NEXT launch. Configured in \`../app.json\`: \`"update": true\` = the
+project's live bundle on the platform (a pushed project), \`"update": { "url": "https://…/app.js" }\`
+= your own hosting, \`false\` = off. Sync writes the URL into
 \`lecodes-runtime/src/main/AndroidManifest.xml\` (meta-data \`io.letary.lecodes.UPDATE_URL\`). A
-download runs only when it is of this shell's SDK major and not older than the bundle running; a
-store update always wins over a downloaded bundle. A shell generated before OTA existed reads
-\`assets/app.js\` itself — replace that with:
+download runs only when it is of this shell's SDK major and not older than the bundle running. A
+store update keeps a downloaded bundle only when it is newer code than the one the update ships
+(by compile date); otherwise the store build wins. A shell generated before OTA existed reads
+\`assets/app.js\` itself, and one generated before the first-launch wait calls
+\`LeCodesShell.boot(engine, getApplication<Application>())\` (which never waits) — replace either
+with:
 
 \`\`\`kotlin
-if (!LeCodesShell.boot(engine, getApplication<Application>())) Log.e("LeCodes", "bundled app.js is missing — run \`lecodes app sync\`")
+if (!LeCodesShell.boot(engine, activity)) Log.e("LeCodes", "bundled app.js is missing — run \`lecodes app sync\`")
 \`\`\`
 - Push: the notification service needs \`app/google-services.json\` from the le.codes Firebase
   project; \`lecodes app sync\` applies the google-services Gradle plugin only when that file
@@ -467,7 +566,31 @@ export const urlSchemeFilter = (urlScheme?: string): string => !urlScheme ? "" :
             </intent-filter>
             <!-- /lecodes:urlScheme -->`
 
-export const appManifestTemplate = (urlScheme?: string): string => `<?xml version="1.0" encoding="utf-8"?>
+/** The verified-link intent-filters of app.json "appLinks" (`restampManifestAppLinks`): one
+ *  `autoVerify` filter per host — the `<data>` elements of one filter cross-multiply, so a host's
+ *  paths stay in its own filter; a root link (no path) takes the whole host. Empty without links. */
+export const appLinksFilter = (links: AppLink[]): string => {
+  if (links.length === 0) return ""
+  const hosts = [...new Set(links.map(l => l.host))]
+  const filters = hosts.map(host => {
+    const paths = links.filter(l => l.host === host).map(l => l.path)
+    const prefixes = paths.includes("") ? [] : paths
+    return `
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" />
+                <data android:host="${host}" />${prefixes.map(p => `
+                <data android:pathPrefix="${p}" />`).join("")}
+            </intent-filter>`
+  }).join("")
+  return `
+            <!-- lecodes:appLinks — app.json "appLinks": the verified https links the app opens on (the "url" app event); each host serves /.well-known/assetlinks.json -->${filters}
+            <!-- /lecodes:appLinks -->`
+}
+
+export const appManifestTemplate = (urlScheme?: string, appLinks: AppLink[] = []): string => `<?xml version="1.0" encoding="utf-8"?>
 <!-- Generated by \`lecodes app init\` — yours to edit. Sync leaves it alone, except that with
      app.json "icon" set it restamps the android:icon VALUE to the generated @mipmap set.
      Plugin permissions/services arrive through the plugin modules' own manifests via the AGP
@@ -492,7 +615,7 @@ export const appManifestTemplate = (urlScheme?: string): string => `<?xml versio
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
-            </intent-filter>${urlSchemeFilter(urlScheme)}
+            </intent-filter>${urlSchemeFilter(urlScheme)}${appLinksFilter(appLinks)}
         </activity>
     </application>
 
@@ -616,12 +739,14 @@ class AppViewModel(application: Application) : AndroidViewModel(application) {
     fun onActivityCreate(activity: Activity) {
         engine.attach(activity)
         if (!isCreated) {
-            // OTA (native, no JS involved): LeCodesShell.boot starts the check FIRST — even a bundle
-            // that crashes on boot can never block its own fix — then runs the newest local bundle
-            // (a downloaded update, or the embedded assets/app.js). New code applies on the next
-            // launch. Configured via app.json "update" (→ the runtime module's manifest meta-data);
-            // offline: no-op.
-            if (!LeCodesShell.boot(engine, getApplication<Application>())) {
+            // OTA (native, no JS involved): LeCodesShell.boot takes the newest local bundle (a
+            // downloaded update, or the embedded assets/app.js) and starts the check BEFORE it runs
+            // — even a bundle that crashes on boot can never block its own fix. The first launch of
+            // this binary waits for the check (5 s at most; the splash stays, the first frame is
+            // held) and runs the newest bundle; later launches run at once and new code applies on
+            // the next launch. Configured via app.json "update" (→ the runtime module's manifest
+            // meta-data); offline: no wait.
+            if (!LeCodesShell.boot(engine, activity)) {
                 android.util.Log.e("LeCodes", "bundled app.js is missing — run \`lecodes app sync\`")
             }
             isCreated = true
@@ -631,13 +756,11 @@ class AppViewModel(application: Application) : AndroidViewModel(application) {
 `
 
 export const themesXmlTemplate = (): string => `<resources>
-    <style name="Theme.LeCodesApp" parent="Theme.AppCompat.Light.NoActionBar">
-        <item name="android:windowTranslucentNavigation">true</item>
-        <item name="android:statusBarColor">@android:color/transparent</item>
-        <item name="android:windowNoTitle">true</item>
-        <item name="android:windowTranslucentStatus">true</item>
-        <item name="android:windowBackground">@color/black</item>
-    </style>
+    <!-- The app's theme. Its parent, Theme.LeCodesRuntime (the CLI-owned lecodes-runtime module),
+         carries the window setup and app.json "splash" — the launch window and Android 12+'s
+         system splash; keep that parent and set no android:windowBackground here, or the splash
+         is lost. Your own items go inside. -->
+    <style name="Theme.LeCodesApp" parent="Theme.LeCodesRuntime" />
 </resources>
 `
 

package/src/commands/app/templates/ios.ts

@@ -636,6 +636,69 @@ export const LAUNCH_STORYBOARD = `<?xml version="1.0" encoding="UTF-8" standalon
 </document>
 `
 
+/** App/Base.lproj/LaunchScreen.storyboard as sync writes it when app.json sets "splash" (the file
+ *  is CLI-owned then; without the key it stays the person's, LAUNCH_STORYBOARD of init): the view's
+ *  colour is the colorset LeCodesSplashBackground, the image — when there is one — a size×size pt
+ *  UIImageView (aspect fit; "splash.size", 160 by default) of the imageset LeCodesSplash centred on
+ *  the view. Both live in Assets.xcassets, which
+ *  the project already compiles, so no pbxproj edit. `rgb` (0xRRGGBB) only feeds the storyboard's
+ *  resource cache (Interface Builder's preview); the app reads the colorset. LeCodesShellViewController
+ *  mounts this same storyboard over its container until the first frame. */
+export const splashStoryboardTemplate = (image: boolean, rgb: number, size = 160): string => {
+  const channel = (shift: number) => String(((rgb >> shift) & 0xff) / 255)
+  // The frame is Interface Builder's preview on its 375×667 canvas; the constraints place the view.
+  const x = (375 - size) / 2, y = (667 - size) / 2
+  const imageView = image ? `
+                        <subviews>
+                            <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFit" horizontalHuggingPriority="251" verticalHuggingPriority="251" image="LeCodesSplash" translatesAutoresizingMaskIntoConstraints="NO" id="LcS-im-001">
+                                <rect key="frame" x="${x}" y="${y}" width="${size}" height="${size}"/>
+                                <constraints>
+                                    <constraint firstAttribute="width" constant="${size}" id="LcS-cw-001"/>
+                                    <constraint firstAttribute="height" constant="${size}" id="LcS-ch-001"/>
+                                </constraints>
+                            </imageView>
+                        </subviews>` : ""
+  const centre = image ? `
+                        <constraints>
+                            <constraint firstItem="LcS-im-001" firstAttribute="centerX" secondItem="Ze5-6b-2t3" secondAttribute="centerX" id="LcS-cx-001"/>
+                            <constraint firstItem="LcS-im-001" firstAttribute="centerY" secondItem="Ze5-6b-2t3" secondAttribute="centerY" id="LcS-cy-001"/>
+                        </constraints>` : ""
+  return `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Generated by \`lecodes app sync\` from app.json "splash" — regenerated on every sync, do not edit. -->
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="13122.16" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <dependencies>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="13104.12"/>
+        <capability name="Named colors" minToolsVersion="9.0"/>
+        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
+    </dependencies>
+    <scenes>
+        <!--View Controller-->
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <rect key="frame" x="0.0" y="0.0" width="375" height="667"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>${imageView}
+                        <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
+                        <color key="backgroundColor" name="LeCodesSplashBackground"/>${centre}
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+    <resources>${image ? `
+        <image name="LeCodesSplash" width="${size}" height="${size}"/>` : ""}
+        <namedColor name="LeCodesSplashBackground">
+            <color red="${channel(16)}" green="${channel(8)}" blue="${channel(0)}" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
+        </namedColor>
+    </resources>
+</document>
+`
+}
+
 export const ASSETS_ROOT_JSON = `{
   "info" : {
     "author" : "xcode",
@@ -703,8 +766,16 @@ export interface RuntimePlugin {
   id: string
   /** Swift packages the target links (manifest ios.packages). */
   packages?: IosPackage[]
+  /** The binary targets the target links (manifest ios.binaries), by name: the xcframeworks sync
+   *  copies to `runtimeBinaryPath(id, name)`. */
+  binaries?: string[]
 }
 
+/** Where sync copies a plugin's prebuilt xcframework (manifest ios.binaries), relative to the
+ *  LeCodesRuntime package: inside it, as SwiftPM takes a binary target's path, beside the vendored
+ *  sources and with the same lifecycle (replaced on every sync, removed with the plugin). */
+export const runtimeBinaryPath = (id: string, name: string): string => `Binaries/${id}/${name}.xcframework`
+
 /** The SDK's engine variants — one tag of lecodes-ios-sdk per variant (`<version>` = full,
  *  `<version>-3d`, `-2d`, `-core`): core = UI only, 2d = + the 2D engine, 3d = + Filament with Jolt,
  *  full = everything. The Swift sources are the same; the engine binary differs. */
@@ -722,8 +793,9 @@ export const sdkProducts = (variant: SdkVariant): string[] =>
 /** LeCodesRuntime/Package.swift — the CLI-owned dependency graph: the SDK (one tag per
  *  variant, pinned with `.exact(…)`: the variant is the engine binary the tag's manifest names,
  *  so SwiftPM must never drift on its own — moving the version is the CLI's job, `lecodes app
- *  update` or app.json ios.sdk) + one vendored target per installed plugin. The SDK's assets
- *  (the 3D variants' shader archives) ride inside the package. */
+ *  update` or app.json ios.sdk) + one vendored target per installed plugin, + a binary target per
+ *  xcframework a plugin carries (its copy under Binaries/<id>/). The SDK's assets (the 3D variants'
+ *  shader archives) ride inside the package. */
 export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant, plugins: RuntimePlugin[], sdkPath?: string): string => {
   const sdkDep = (name: string) => `.product(name: "${name}", package: "lecodes-ios-sdk")`
   // LECODES_IOS_SDK_PATH: the SDK-development loop — a package tree on disk (release-ios-sdk.sh
@@ -746,18 +818,31 @@ export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant,
   }
   const packageDecls = [...packages.values()].map(pkg =>
     `\n        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`).join("")
+  // The plugins' prebuilt xcframeworks (manifest ios.binaries): a binary target each, by its copy's
+  // path. A name is one target of the package — two plugins carrying one alike cannot both link.
+  const targetNames = new Map<string, string>([["LeCodesRuntime", "the runtime's own target"], ...plugins.map(p => [p.module, `the module of "${p.id}"`] as [string, string])])
+  for (const p of plugins) {
+    for (const name of p.binaries ?? []) {
+      const prior = targetNames.get(name)
+      if (prior) throw new Error(`Plugin "${p.id}" carries the binary ${name} and ${name} is ${prior} — one name is one target of the shell's package.`)
+      targetNames.set(name, `a binary of "${p.id}"`)
+    }
+  }
   const pluginTargets = plugins.map(p => {
     const deps = [
       sdkDep("LeCodes"),
       ...(p.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
+      ...(p.binaries ?? []).map(name => `"${name}"`),
     ]
+    const binaries = (p.binaries ?? []).map(name => `
+        .binaryTarget(name: "${name}", path: "${runtimeBinaryPath(p.id, name)}"),`).join("")
     return `
         // plugin: ${p.id} (vendored — see plugins.lock.json)
         .target(
             name: "${p.module}",
             dependencies: [${deps.join(", ")}],
             path: "Sources/${p.module}"
-        ),`
+        ),${binaries}`
   }).join("")
   const runtimeDeps = [...sdkProducts(variant).map(sdkDep), ...plugins.map(p => `"${p.module}"`)]
   return `// swift-tools-version:5.9
@@ -877,7 +962,7 @@ Yours — \`lecodes app sync\` never touches these:
   ≥1024px image and every sync renders AppIcon.png from it (flattened over \`"iconBackground"\`,
   default white — App Store icons must be opaque). Or leave the key unset and drop a
   1024×1024 PNG into AppIcon.appiconset/ yourself — sync never touches it then.
-- \`App/Base.lproj/LaunchScreen.storyboard\`
+- \`App/Base.lproj/LaunchScreen.storyboard\` — unless \`app.json\` sets \`"splash"\` (below)
 
 CLI-owned — regenerated on every sync, hand edits are overwritten:
 
@@ -888,10 +973,18 @@ CLI-owned — regenerated on every sync, hand edits are overwritten:
 - \`App/App.entitlements\` — the capabilities the installed plugins declare (e.g. push)
 - \`LeCodesRuntime/\` — local Swift package: the lecodes-ios-sdk dependency (one tag per engine
   variant), vendored plugin sources (Sources/<Module>/), and LeCodesAppViewController — the SDK's
-  shell controller with this project's plugins registered (App/ViewController.swift subclasses it)
+  shell controller with this project's plugins registered (App/ViewController.swift subclasses it).
+  A plugin's prebuilt xcframeworks (its manifest's \`ios.binaries\`) are copied to
+  Binaries/<plugin id>/: binary targets its vendored target links
 - the version values inside \`App.xcodeproj/project.pbxproj\` (from app.json)
 - this README
 
+CLI-owned **only when** \`../app.json\` sets \`"splash"\` — regenerated on every sync then;
+without the key sync never touches them (see "Splash screen"):
+
+- \`App/Base.lproj/LaunchScreen.storyboard\`
+- \`App/Assets.xcassets/LeCodesSplashBackground.colorset/\`, \`App/Assets.xcassets/LeCodesSplash.imageset/\`
+
 ## SDK variant
 
 Sync pins the SDK tag of the smallest engine variant that covers what the compiled bundle actually
@@ -900,30 +993,48 @@ physics, ~10 MB heavier), or \`full\` (everything) — \`<version>-core\`, \`-2d
 bare \`<version>\` for full. Adding your first 3D scene or 2D game to the project switches it
 automatically on the next sync; set \`ios.variant\` in \`../app.json\` to pin one instead.
 
+## Splash screen
+
+\`"splash": { "background": "#RRGGBB", "image": "./splash.png", "size": 160 }\` in \`../app.json\`
+(every key optional) makes every sync write the launch screen: a full-screen view of the colour
+(\`background\`, default \`"iconBackground"\`, default white) with the image fitted centred into a
+\`size\`×\`size\` pt square (160 by default) — never at its pixel size — from @1x/@2x/@3x renderings
+(size × 1/2/3 px: 160/320/480 at the default) of the one master. Use a square mark of at least
+3 × size px (a non-square one is fitted into the square, a smaller one is upscaled); the same key
+draws the Android splash, which crops the mark to a circle on Android 12+ — above a \`size\` of 192
+its corners are cut there (sync warns; 288 is the most it takes). No image = the colour alone. The app holds this screen until its first frame — through the
+first-launch wait of an OTA shell too — so nothing flashes between the two. iOS caches launch
+screens: after a change, delete the app from the device (or restart the device) to see the new one.
+
 ## Over-the-air updates
 
 With \`"update": true\` in \`../app.json\` (server-backed projects; or
 \`"update": {"url": "https://…/app.js"}\` for any static hosting), the app checks that URL
 at launch — natively, before any JS runs, so a broken bundle can never block its own fix.
-Unchanged code costs a ~0-byte 304; new code downloads in the background and runs on the
-NEXT launch. Offline it's a silent no-op — the app always launches from a local bundle.
-An App Store update always beats a cached OTA bundle. JS only: adding/removing native
-plugins still needs a store release.
+Unchanged code costs a ~0-byte 304. The FIRST launch of an installed build waits for the answer
+(5 s at most, the launch screen held on screen) and runs the newest bundle at once, so a fresh
+install from the App Store never starts on the older code it shipped with; every later launch
+runs the local bundle at once, new code downloads in the background and runs on the NEXT launch.
+Offline it's a silent no-op with no wait — the app always launches from a local bundle. An App
+Store update keeps a downloaded bundle only when it is newer code than the one the update ships
+(by compile date); otherwise the store build wins. JS only: adding/removing native plugins still
+needs a store release.
 
 Shipping an update is just \`lecodes push --publish\` — no rebuild, no store review:
 running apps download the new code on their next launch and run it on the launch after.
 
 Shells generated before OTA support have a \`ViewController.swift\` that reads app.js from
 \`Bundle.main\` directly, so downloaded updates would never run — and since \`App/*.swift\`
-is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Replace the
-\`Bundle.main\` load with:
+is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Make it subclass
+\`LeCodesAppViewController\` (the boot above, the first-launch wait included), or replace the
+\`Bundle.main\` load with (no wait):
 
 \`\`\`swift
-LeCodesUpdater.checkForUpdate()
 guard let code = LeCodesUpdater.activeBundle() else {
     print("LeCodes: bundled app.js is missing — run \`lecodes app sync\`")
     return
 }
+LeCodesUpdater.checkForUpdate()
 engine.run(code)
 \`\`\`