lecodes-cli 2.4.2 → 2.4.3

package/src/commands/app/android.ts

@@ -11,16 +11,17 @@ import {
   type AppConfig, ANDROID_SDK_VARIANTS, type AndroidSdkVariant, VERSION_RE, androidSdkArtifact, androidVariantEngines,
   childEnv, cmpVersion, ensureShellIgnored, fetchLatestSdkVersion,
   projectRoot, readAppConfigAt, readJson, resolvePlugin, resolveSdkVersion, resolveVariant, runTool, sdkSatisfies, slugify,
-  writeJson, type LockEntry, resolveUpdateUrl, urlSchemeOf,
+  writeJson, type LockEntry, resolveUpdateUrl, urlSchemeOf, appLinksOf, appLinksSiteNote, type AppLink,
 } from "./shared"
 import { loadIconMaster, restampManifestIcon, writeAndroidIcons } from "./icon"
+import { androidSplashThemeHint, loadSplashMaster, writeAndroidSplash } from "./splash"
 import {
   ANDROID_GITIGNORE, ANDROID_README, APP_PROGUARD_RULES, COLORS_XML, GRADLE_PROPERTIES, GRADLE_VERSION,
   GRADLE_PLUGIN_VERSIONS, IC_LAUNCHER_XML, aarWrapperBuildGradle, appBuildGradleTemplate,
   appManifestTemplate, appViewModelTemplate, gradleWrapperProperties, mainActivityTemplate,
   pluginBuildGradleTemplate, rootBuildGradleTemplate, runtimeBuildGradleTemplate,
-  runtimeKotlinTemplate, settingsGradleTemplate, stringsXmlTemplate, themesXmlTemplate,
-  type AndroidRuntimePlugin, type AndroidShellIdentity, runtimeManifestTemplate, urlSchemeFilter,
+  runtimeKotlinTemplate, runtimeThemeTemplate, settingsGradleTemplate, stringsXmlTemplate, themesXmlTemplate,
+  type AndroidRuntimePlugin, type AndroidShellIdentity, runtimeManifestTemplate, urlSchemeFilter, appLinksFilter,
 } from "./templates/android"
 import { GRADLEW_BAT, GRADLEW_SH } from "./templates/gradlew"
 
@@ -38,6 +39,10 @@ export const ANDROID_SDK_REPO = "letary/lecodes-android-sdk"
  *  :lecodes-ui). A 2.x bundle is refused by a 1.x runtime (`_creatorApp.run()` gates on the major),
  *  so a shell pinned below this would install and show nothing; `lecodes app update` moves a 1.x
  *  shell here. (1.2.0 was the 1.x floor: system back moved into engine.attach().) */
+// TODO(docs/plans/ota-splash-plan.md step 1): raise to the first lecodes-android-sdk release with
+// `LeCodesShell.boot(engine, activity, …)` (the first-launch wait + the splash hold), which the
+// AppViewModel template now calls — the owner fills the version in at release time. (Against an
+// older AAR the call still compiles: it lands on the context form, which never waits.)
 export const ANDROID_SDK_MIN_VERSION = "2.0.13"
 
 /** First lecodes-android-sdk release that publishes the variant matrix (lecodes-sdk-3d / -2d /
@@ -171,7 +176,7 @@ export const initAndroid = async (opts: AndroidInitOptions) => {
 
   write("app/build.gradle.kts", appBuildGradleTemplate(identity, config.android!.minify ?? true))
   write("app/proguard-rules.pro", APP_PROGUARD_RULES)
-  write("app/src/main/AndroidManifest.xml", appManifestTemplate(urlSchemeOf(config)))
+  write("app/src/main/AndroidManifest.xml", appManifestTemplate(urlSchemeOf(config), appLinksOf(config)))
   write(`app/src/main/java/${pkgPath}/MainActivity.kt`, mainActivityTemplate(identity.applicationId))
   write(`app/src/main/java/${pkgPath}/AppViewModel.kt`, appViewModelTemplate(identity.applicationId))
   write("app/src/main/res/values/themes.xml", themesXmlTemplate())
@@ -184,6 +189,8 @@ export const initAndroid = async (opts: AndroidInitOptions) => {
   const initArtifact = cmpVersion(sdkVersion, ANDROID_SDK_VARIANTS_MIN) >= 0 ? androidSdkArtifact(initVariant, sdkVersion) : "lecodes-sdk"
   write("lecodes-runtime/build.gradle.kts", runtimeBuildGradleTemplate(sdkVersion, [], initArtifact))
   write("lecodes-runtime/src/main/kotlin/io/letary/lecodes/runtime/LeCodesRuntime.kt", runtimeKotlinTemplate([]))
+  // The parent of app/'s Theme.LeCodesApp (black until a sync renders app.json "splash" into it).
+  write("lecodes-runtime/src/main/res/values/lecodes_splash.xml", runtimeThemeTemplate())
 
   log("")
   log(`${c.green("sdk")}       lecodes-android-sdk ${sdkVersion}${sdk === "latest" ? c.dim("  (android.sdk: latest — re-resolved on every sync)") : c.dim("  (pinned in app.json android.sdk — `lecodes app update` moves it)")}`)
@@ -191,6 +198,7 @@ export const initAndroid = async (opts: AndroidInitOptions) => {
   log(`  ${c.bold("lecodes app sync")}            embed the compiled bundle (+ plugins) into the shell`)
   log(`  ${c.bold("lecodes app open android")}    then run on your device from Android Studio`)
   log(`  App icon: set app.json "icon" to a square ≥1024px image — sync renders every size (or use Android Studio → Image Asset)`)
+  log(`  Splash: set app.json "splash": {"background": "#RRGGBB", "image": "./splash.png"} — sync renders the splash (the image centred at 160 dp, "size" overrides; Android 12+'s system splash included)`)
 }
 
 /* ---------------------------------------- sync ---------------------------------------- */
@@ -378,7 +386,14 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
   // LeCodesShell.boot reads it — app.json "update" resolved like the iOS plist key ----
   const updateUrl = resolveUpdateUrl(config.update, root, sdkVersion)
   writeFileSync(join(androidDir, "lecodes-runtime", "src", "main", "AndroidManifest.xml"), runtimeManifestTemplate(updateUrl))
-  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch (LeCodesShell.boot), new code applies next launch`)
+  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch (LeCodesShell.boot): the first launch of a build waits (≤ 5 s) for the newest bundle, later launches apply new code next launch`)
+  // ---- splash: Theme.LeCodesRuntime (the parent of the app's theme) in the runtime module's res —
+  // black without app.json "splash", the splash colour / image / Android 12+ system splash with it ----
+  await writeAndroidSplash(androidDir, await loadSplashMaster(root, config))
+  if (config.splash !== undefined) {
+    const themeHint = androidSplashThemeHint(androidDir)
+    if (themeHint) warn(`splash: ${themeHint}`)
+  }
 
   if (pluginSpecs.length > 0 || existsSync(lockPath)) writeJson(lockPath, { plugins: newLock })
 
@@ -393,38 +408,59 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
     restampManifestIcon(androidDir)
   }
   restampManifestUrlScheme(androidDir, urlSchemeOf(config))
+  const appLinks = appLinksOf(config)
+  restampManifestAppLinks(androidDir, appLinks)
+  if (appLinks.length) {
+    log(`${c.green("links")}     ${appLinks.map(l => l.url).join(", ")} — verified by the site's proof:`)
+    for (const line of appLinksSiteNote(appLinks, { platform: "android", applicationId: config.android?.applicationId })) log(`            ${line}`)
+  }
 
   log("")
   success(`Android shell synced: app.js + ${runtimePlugins.length} plugin(s), SDK ${sdkVersion}, v${config.version ?? "1.0.0"} (${config.android?.versionCode ?? 1}).`)
   note("Build & run from Android Studio (`lecodes app open android`) — user files in android/app/ were not touched.")
 }
 
-/** The `lecodes:urlScheme` block of the USER-owned manifest follows app.json: written into the
- *  activity when the key appears, rewritten when it changes, removed when it goes. A manifest
+/** A `lecodes:<tag>` block of the USER-owned manifest follows app.json: written into the
+ *  activity when its key appears, rewritten when it changes, removed when it goes. A manifest
  *  without the tag and without a MainActivity to put it in is left alone, with a warning. */
-export const restampManifestUrlScheme = (androidDir: string, urlScheme: string | undefined): void => {
+const restampManifestBlock = (androidDir: string, tag: string, block: string, what: string, missing: string, after: RegExp[] = []): void => {
   const path = join(androidDir, "app", "src", "main", "AndroidManifest.xml")
   if (!existsSync(path)) return
   const content = readFileSync(path, "utf8")
-  const tagged = /\n[ \t]*<!-- lecodes:urlScheme[\s\S]*?<!-- \/lecodes:urlScheme -->/
-  const block = urlSchemeFilter(urlScheme)
+  const tagged = new RegExp(`\\n[ \\t]*<!-- lecodes:${tag}[\\s\\S]*?<!-- \\/lecodes:${tag} -->`)
   let next: string
-  if (tagged.test(content)) next = content.replace(tagged, block)
-  else if (!urlScheme) return
+  if (tagged.test(content)) next = content.replace(tagged, () => block)
+  else if (!block) return
   else {
-    // Inside the MainActivity element: right after its LAUNCHER intent-filter.
+    // Inside the MainActivity element: after the block it follows in the template when that one
+    // is there, else right after the LAUNCHER intent-filter — so a restamped manifest reads as a
+    // fresh init's.
     const launcher = /(<category android:name="android\.intent\.category\.LAUNCHER" \/>\s*<\/intent-filter>)/
-    if (!launcher.test(content)) {
-      warn(`couldn't find the launcher activity in app/src/main/AndroidManifest.xml — add an intent-filter for the "${urlScheme}" scheme yourself.`)
+    const anchor = [...after, launcher].find(re => re.test(content))
+    if (!anchor) {
+      warn(`couldn't find the launcher activity in app/src/main/AndroidManifest.xml — ${missing}`)
       return
     }
-    next = content.replace(launcher, `$1${block}`)
+    next = content.replace(anchor, (m) => `${m}${block}`)
   }
   if (next === content) return
   writeFileSync(path, next)
-  log(`${c.green("updated")}   android/app/src/main/AndroidManifest.xml: urlScheme ${urlScheme ? `→ ${urlScheme}://` : "removed"}`)
+  log(`${c.green("updated")}   android/app/src/main/AndroidManifest.xml: ${what}`)
 }
 
+/** app.json "urlScheme" → the tagged BROWSABLE intent-filter (`urlSchemeFilter`). */
+export const restampManifestUrlScheme = (androidDir: string, urlScheme: string | undefined): void =>
+  restampManifestBlock(androidDir, "urlScheme", urlSchemeFilter(urlScheme),
+    `urlScheme ${urlScheme ? `→ ${urlScheme}://` : "removed"}`,
+    `add an intent-filter for the "${urlScheme}" scheme yourself.`)
+
+/** app.json "appLinks" → the tagged autoVerify intent-filters (`appLinksFilter`). */
+export const restampManifestAppLinks = (androidDir: string, links: AppLink[]): void =>
+  restampManifestBlock(androidDir, "appLinks", appLinksFilter(links),
+    `appLinks ${links.length ? `→ ${links.map(l => l.url).join(", ")}` : "removed"}`,
+    `add the autoVerify intent-filters for ${links.map(l => l.url).join(", ")} yourself.`,
+    [/<!-- \/lecodes:urlScheme -->/])
+
 /** Values-only restamps + tagged-line management in the USER-owned app/build.gradle.kts —
  *  the Android analog of the pbxproj MARKETING_VERSION restamp + CODE_SIGN_ENTITLEMENTS
  *  injection: warn-not-fail when the user restructured, and the ONLY lines sync ever removes
@@ -1025,9 +1061,22 @@ export const doctorAndroidChecks = async (
     check(existsSync(manifest) && readFileSync(manifest, "utf8").includes("io.letary.lecodes.UPDATE_URL"), "OTA update URL in the runtime manifest", "run `lecodes app sync`", false)
     const appSrc = join(androidDir, "app", "src", "main", "java")
     const kt = existsSync(appSrc) ? readdirSync(appSrc, { recursive: true }).map(String).filter((f) => f.endsWith(".kt")) : []
-    const boots = kt.some((f) => readFileSync(join(appSrc, f), "utf8").includes("LeCodesShell.boot"))
+    const sources = kt.map((f) => readFileSync(join(appSrc, f), "utf8"))
+    const boots = sources.some((src) => src.includes("LeCodesShell.boot"))
     check(boots, "App code launches via the updater (LeCodesShell.boot)",
-      "no app/src/main/java/**/*.kt calls LeCodesShell.boot(engine, context) — downloaded updates would never run; see \"Over-the-air updates\" in android/README.md for the AppViewModel snippet", false)
+      "no app/src/main/java/**/*.kt calls LeCodesShell.boot(engine, activity) — downloaded updates would never run; see \"Over-the-air updates\" in android/README.md for the AppViewModel snippet", false)
+    // The context form (the pre-wait shape, `boot(engine, getApplication())`) still runs downloads,
+    // but only from the NEXT launch: no view to hold, so the first launch of a build never waits.
+    const waits = sources.some((src) => /LeCodesShell\.boot\(\s*engine\s*,\s*activity\b/.test(src))
+    if (boots) check(waits, "The first launch waits for the newest bundle (LeCodesShell.boot(engine, activity))",
+      "AppViewModel calls the context form of LeCodesShell.boot — pass the activity instead (onActivityCreate's parameter) so a fresh install runs the newest bundle at once; see \"Over-the-air updates\" in android/README.md", false)
+  }
+
+  if (config.splash !== undefined) {
+    // The splash lives in Theme.LeCodesRuntime (the runtime module); the user-owned app theme must
+    // inherit it — a shell generated before the key existed is parented on AppCompat directly.
+    const themeHint = androidSplashThemeHint(androidDir)
+    check(!themeHint, "The app theme inherits the splash (Theme.LeCodesRuntime)", themeHint ?? "", false)
   }
 
   const signing = resolveAndroidSigning(androidDir)

package/src/commands/app/index.ts

@@ -3,18 +3,20 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statS
 import { homedir } from "node:os"
 import { basename, dirname, join, resolve } from "node:path"
 import { readManifest } from "../../project/manifest"
+import { binaryName } from "../../plugin/manifest"
 import { compileShell, type BundleResource } from "../compile"
 import { CliError, UsageError, bool, c, defineCommand, log, note, str, success, warn } from "../../cli"
 import {
   ACCENT_COLOR_JSON, APP_DELEGATE, APP_ICON_JSON, ASSETS_ROOT_JSON, IOS_README, LAUNCH_STORYBOARD,
   SCENE_DELEGATE, SCHEME_XML, VIEW_CONTROLLER, entitlementsTemplate, infoPlistTemplate,
-  pbxprojTemplate, runtimePackageTemplate, runtimeSwiftTemplate,
+  pbxprojTemplate, runtimeBinaryPath, runtimePackageTemplate, runtimeSwiftTemplate,
   type RuntimePlugin, type SdkVariant, type ShellIdentity,
 } from "./templates/ios"
 import {
   FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, ensureShellIgnored,
   fetchLatestSdkVersion, latestPluginTag, localPlugin, localPluginKey, pluginSpecsFor, projectRoot, readAppConfigAt, readJson, resolvePlugin, resolveSdkVersion, sdkSatisfies,
   resolveVariant, runTool, slugify, writeJson, VERSION_RE, type AppConfig, type LockEntry, resolveUpdateUrl, urlSchemeOf,
+  appLinksOf, appLinksSiteNote, associatedDomainsOf,
 } from "./shared"
 import { isLocalPluginSpec, type PluginEntry } from "lecodes-sdk/compile"
 import {
@@ -23,6 +25,14 @@ import {
 } from "./android"
 import { desktopBuild, initDesktop } from "./desktop"
 import { loadIconMaster, writeIosAppIcon } from "./icon"
+import { loadSplashMaster, writeIosSplash } from "./splash"
+
+/** The entitlements of app.json alone (init, before any plugin): the associated domains of
+ *  "appLinks". Sync merges the plugins' values on top of these. */
+const iosEntitlements = (base: Record<string, unknown>, config: AppConfig): Record<string, unknown> => {
+  const domains = associatedDomainsOf(appLinksOf(config))
+  return domains.length ? { ...base, "com.apple.developer.associated-domains": domains } : base
+}
 
 /*
  * `lecodes app` — native app shells for a LeCodes project (docs/xcode-app-plan.md). This file is
@@ -68,6 +78,10 @@ const SDK_REPO = "letary/lecodes-ios-sdk"
 // it); this floor is only the last-resort fallback when the network is unavailable at init. A 1.x
 // shell is moved here by `lecodes app update` (its CLI-owned files are regenerated; its
 // App/ViewController.swift keeps compiling: LeCodesViewController and LeCodesUpdater exist in 2.x).
+// TODO(docs/plans/ota-splash-plan.md step 1): raise to the first lecodes-ios-sdk release with the
+// first-launch wait (LeCodesShell.boot's `firstLaunchTimeout` + the launch-screen hold of
+// LeCodesShellViewController) — the owner fills the version in at release time. (An older SDK
+// still builds the generated shell: it just never waits.)
 const SDK_MIN_VERSION = "2.0.7"
 
 // First lecodes-ios-sdk release with `LeCodesEngine.bootProjectUuid` — the shell's world
@@ -167,7 +181,7 @@ const initIos = async (opts: IosInitOptions): Promise<void> => {
   write("App/SceneDelegate.swift", SCENE_DELEGATE)
   write("App/ViewController.swift", VIEW_CONTROLLER)
   write("App/Info.plist", infoPlistTemplate({}, undefined, urlSchemeOf(config)))
-  write("App/App.entitlements", entitlementsTemplate({}))
+  write("App/App.entitlements", entitlementsTemplate(iosEntitlements({}, config)))
   write("App/Base.lproj/LaunchScreen.storyboard", LAUNCH_STORYBOARD)
   write("App/Assets.xcassets/Contents.json", ASSETS_ROOT_JSON)
   write("App/Assets.xcassets/AccentColor.colorset/Contents.json", ACCENT_COLOR_JSON)
@@ -183,6 +197,7 @@ const initIos = async (opts: IosInitOptions): Promise<void> => {
   log(`  ${c.bold("lecodes app sync")}          embed the compiled bundle (+ plugins) into the shell`)
   log(`  ${c.bold("open ios/App.xcodeproj")}    then run on your device from Xcode`)
   log(`  App icon: set app.json "icon" to a square ≥1024px image — sync renders every size (or drop a PNG into App/Assets.xcassets/AppIcon.appiconset/)`)
+  log(`  Splash: set app.json "splash": {"background": "#RRGGBB", "image": "./splash.png"} — sync writes the launch screen (the image centred at 160 pt, "size" overrides; or edit App/Base.lproj/LaunchScreen.storyboard yourself)`)
 }
 
 const init = defineCommand({
@@ -256,7 +271,9 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   const entitlementValues: Record<string, unknown[]> = {}
   const newLock: Record<string, LockEntry> = {}
 
-  const sourcesDir = join(iosDir, "LeCodesRuntime", "Sources")
+  const runtimeDir = join(iosDir, "LeCodesRuntime")
+  const sourcesDir = join(runtimeDir, "Sources")
+  const binariesDir = join(runtimeDir, "Binaries")
   for (const [id, spec] of pluginSpecs) {
     const plugin = resolvePlugin(id, spec, oldLock[id], "ios")
     const ios = plugin.manifest.ios!
@@ -269,6 +286,11 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
     const dest = join(sourcesDir, module)
     rmSync(dest, { recursive: true, force: true })
     cpSync(src, dest, { recursive: true })
+    // Its prebuilt xcframeworks (manifest ios.binaries) beside the sources, replaced the same way:
+    // a binary target's path is inside the package (SwiftPM takes none outside it).
+    const binaries = (ios.binaries ?? []).map(path => ({ path, name: binaryName(path) }))
+    rmSync(join(binariesDir, id), { recursive: true, force: true })
+    for (const b of binaries) cpSync(join(plugin.dir, b.path), join(runtimeDir, runtimeBinaryPath(id, b.name)), { recursive: true, verbatimSymlinks: true })
 
     // Hard error, not a warning: outside the plugin's `sdk` range the vendored sources reference
     // an SDK API the linked release does not have (or another contract major), so the shell
@@ -287,9 +309,9 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
         throw new CliError(`Plugin "${id}": manifest ios.packages entries need { url, exact | from, products: [...] } — got ${JSON.stringify(pkg)}`)
       }
     }
-    runtimePlugins.push({ id, module, register, packages: ios.packages })
+    runtimePlugins.push({ id, module, register, packages: ios.packages, binaries: binaries.map(b => b.name) })
     newLock[id] = plugin.lock
-    log(`${c.green("plugin")}    ${id}@${plugin.lock.version} (${plugin.lock.tag} → Sources/${module})`)
+    log(`${c.green("plugin")}    ${id}@${plugin.lock.version} (${plugin.lock.tag} → Sources/${module}${binaries.length ? `, Binaries/${id}` : ""})`)
   }
 
   // Remove targets of uninstalled plugins (everything under Sources/ except the runtime itself).
@@ -300,6 +322,15 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
       log(`${c.yellow("removed")}   ios/LeCodesRuntime/Sources/${entry}  (plugin uninstalled)`)
     }
   }
+  // …and their binaries (Binaries/<id>/); the folder goes with the last of them.
+  const installed = new Set(runtimePlugins.map(p => p.id))
+  for (const entry of existsSync(binariesDir) ? readdirSync(binariesDir) : []) {
+    if (!installed.has(entry) && statSync(join(binariesDir, entry)).isDirectory()) {
+      rmSync(join(binariesDir, entry), { recursive: true })
+      log(`${c.yellow("removed")}   ios/LeCodesRuntime/Binaries/${entry}  (plugin uninstalled)`)
+    }
+  }
+  if (existsSync(binariesDir) && readdirSync(binariesDir).length === 0) rmSync(binariesDir, { recursive: true })
 
   // ---- bundle: compile self-contained into Resources/, then embed the assets it references ----
   const remotePatterns = config.resources?.remote ?? []
@@ -375,7 +406,7 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   for (const [key, values] of Object.entries(infoValues)) mergedKeys[key] = [...new Set(values)].join(" ")
   const updateUrl = resolveUpdateUrl(config.update, root, sdkVersion)
   writeFileSync(join(iosDir, "App", "Info.plist"), infoPlistTemplate(mergedKeys, updateUrl, urlSchemeOf(config)))
-  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch, new code applies next launch${config.update === undefined ? c.dim('  ("update": false in app.json turns it off)') : ""}`)
+  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch: the first launch of a build waits (≤ 5 s) for the newest bundle, later launches apply new code next launch${config.update === undefined ? c.dim('  ("update": false in app.json turns it off)') : ""}`)
   else if (config.update === false) log(`${c.green("update")}    off (app.json "update": false)`)
   else note(`no OTA: a local-only project has no bundle on the platform — push it, or set "update": {"url": "https://…/app.js"} for custom hosting`)
 
@@ -393,6 +424,13 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   // get the CODE_SIGN_ENTITLEMENTS reference injected the first time a plugin brings a
   // capability — the ONE structural pbxproj edit sync ever makes, idempotent and line-shaped.
   const mergedEntitlements: Record<string, unknown> = {}
+  // app.json "appLinks" → associated-domains, merged like a plugin's array value (a plugin may
+  // declare the key too, e.g. a web-credentials domain). The key gone = the domains gone: the
+  // file is regenerated whole.
+  const appLinks = appLinksOf(config)
+  if (appLinks.length) {
+    (entitlementValues["com.apple.developer.associated-domains"] ??= []).unshift(associatedDomainsOf(appLinks))
+  }
   for (const [key, values] of Object.entries(entitlementValues)) {
     if (values.every(v => Array.isArray(v))) {
       const seen = new Set<string>()
@@ -405,6 +443,10 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
       mergedEntitlements[key] = values[0]
     }
   }
+  if (appLinks.length) {
+    log(`${c.green("links")}     ${appLinks.map(l => l.url).join(", ")} — verified by the site's proof:`)
+    for (const line of appLinksSiteNote(appLinks, { platform: "ios", teamId: config.ios?.teamId, bundleId: config.ios?.bundleId })) log(`            ${line}`)
+  }
   const hasEntitlements = Object.keys(mergedEntitlements).length > 0
   if (pbx.includes("CODE_SIGN_ENTITLEMENTS") || hasEntitlements) {
     writeFileSync(join(iosDir, "App", "App.entitlements"), entitlementsTemplate(mergedEntitlements))
@@ -426,6 +468,11 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   if (config.icon) {
     await writeIosAppIcon(iosDir, await loadIconMaster(root, config))
   }
+  // ---- splash: the launch storyboard from app.json "splash" when set (it becomes CLI-owned with
+  // its colorset / imageset) — absent, the storyboard stays the person's ----
+  if (config.splash !== undefined) {
+    await writeIosSplash(iosDir, await loadSplashMaster(root, config))
+  }
 
   log("")
   success(`Shell synced: app.js + ${runtimePlugins.length} plugin(s), SDK ${sdkVersion}, variant ${variant}, v${config.version ?? "1.0.0"} (${config.ios.buildNumber ?? 1}).`)
@@ -437,7 +484,7 @@ const sync = defineCommand({
   name: "sync",
   summary: "Make every existing shell match the project: bundle + assets + SDK variant + plugins + CLI-owned files",
   usage: "[ios|android]",
-  description: "Compiles the bundle and embeds the assets it references (ios/App/Resources/ resp. the android assets/; offline by default, also for server projects — app.json \"resources\": {\"remote\": [globs]} keeps heavy assets streaming), picks the SDK variant from the bundle's engine use, vendors the app.json plugins (pinned in plugins.lock.json) and regenerates the CLI-owned shell files. User files (ios/App/*.swift, android/app/) are never touched.\n\nNative OTA JS updates at launch (both shells; the current launch runs the newest LOCAL bundle, a download applies on the next): on by default for a pushed project (its bundle on the platform, the launcher's own URL), app.json \"update\": {\"url\": …} for custom hosting, \"update\": false turns it off. A download runs only when it is of the shell's SDK major and not older than the bundle running. app.json \"icon\" (a square ≥1024px image) renders the app icons every sync (\"iconBackground\": the adaptive / flatten backdrop). app.json \"urlScheme\" (\"myshop\") is the scheme the shells open on: iOS CFBundleURLTypes, Android a BROWSABLE intent-filter — a link arrives as app.launchUrl / the \"url\" event (the return of Browser.open with a returnUrl). No platform = every shell that exists; a dual-shell project compiles once.",
+  description: "Compiles the bundle and embeds the assets it references (ios/App/Resources/ resp. the android assets/; offline by default, also for server projects — app.json \"resources\": {\"remote\": [globs]} keeps heavy assets streaming), picks the SDK variant from the bundle's engine use, vendors the app.json plugins (pinned in plugins.lock.json) and regenerates the CLI-owned shell files. User files (ios/App/*.swift, android/app/) are never touched.\n\nNative OTA JS updates at launch (both shells): the first launch of an installed build waits (≤ 5 s, the splash held) for the check and runs the newest bundle; every later launch runs the newest LOCAL bundle and a download applies on the next. On by default for a pushed project (its bundle on the platform, the launcher's own URL), app.json \"update\": {\"url\": …} for custom hosting, \"update\": false turns it off. A download runs only when it is of the 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 it ships. app.json \"icon\" (a square ≥1024px image) renders the app icons every sync (\"iconBackground\": the adaptive / flatten backdrop). app.json \"splash\" ({\"background\": \"#RRGGBB\", \"image\": \"./splash.png\", \"size\": 160}, all optional) renders the launch screen of both shells every sync — the colour with the image fitted centred into a size × size pt / dp square, 160 by default (iOS LaunchScreen.storyboard, Android the system splash of Theme.LeCodesRuntime, which the app's theme inherits). app.json \"urlScheme\" (\"myshop\") is the scheme the shells open on: iOS CFBundleURLTypes, Android a BROWSABLE intent-filter — a link arrives as app.launchUrl / the \"url\" event (the return of Browser.open with a returnUrl). app.json \"appLinks\" ([\"https://shop.example/pay/\"]) are the verified https links they open on — iOS universal links (associated-domains in App.entitlements), Android App Links (autoVerify intent-filters in the manifest); sync prints the apple-app-site-association / assetlinks.json each site must serve. No platform = every shell that exists; a dual-shell project compiles once.",
   examples: ["lecodes app sync", "lecodes app sync android"],
   run: ({ args }) => runSync(args[0]),
 })
@@ -766,7 +813,7 @@ const doctorIosChecks = async (root: string, config: AppConfig, check: Check) =>
 const doctor = defineCommand({
   name: "doctor",
   summary: "Preflight checks for building / uploading the shells",
-  description: "Toolchain (Xcode / JDK + Android SDK), the synced bundle, SDK variant + version vs app.json, plugin lock, signing (team id / release keystore), icons, OTA wiring and the App Store Connect key. Fatal checks fail the command (exit 1); soft ones print a `!` and a hint.",
+  description: "Toolchain (Xcode / JDK + Android SDK), the synced bundle, SDK variant + version vs app.json, plugin lock, signing (team id / release keystore), icons, the splash theme (Android), OTA wiring and the App Store Connect key. Fatal checks fail the command (exit 1); soft ones print a `!` and a hint.",
   examples: ["lecodes app doctor"],
   run: async () => {
     const root = projectRoot()
@@ -782,6 +829,9 @@ const doctor = defineCommand({
     if (config?.icon) {
       check(existsSync(join(root, config.icon)), `Icon master ${config.icon}`, `app.json "icon" points at a missing file — sync will fail`)
     }
+    if (typeof config?.splash?.image === "string") {
+      check(existsSync(join(root, config.splash.image)), `Splash image ${config.splash.image}`, `app.json "splash.image" points at a missing file — sync will fail`)
+    }
     if (hasIos) await doctorIosChecks(root, config!, check)
     if (hasAndroid) {
       await doctorAndroidChecks(root, config!, check)

package/src/commands/app/shared.ts

@@ -49,6 +49,21 @@ export interface AppConfig {
   /** Icon backdrop ("#RGB"/"#RRGGBB", default white): the Android adaptive-icon background
    *  layer, and what a transparent master is flattened onto for the opacity-required iOS icon. */
   iconBackground?: string
+  /** The launch screen of both shells, rendered by every sync (splash.ts): a full-screen colour
+   *  (`background`, any opaque CSS color, default `iconBackground`, default white) and, optionally,
+   *  `image` (project-root-relative PNG/JPEG) fitted CENTRED into a square of a fixed logical side
+   *  on both platforms — `size` pt / dp, a whole number, default 160 — never at its pixel size:
+   *  sync renders every density from the one master (iOS @1x/@2x/@3x = size × 1/2/3 px, Android
+   *  mdpi…xxxhdpi = size × 1/1.5/2/3/4 px), so a master under 3 × size px warns (it would upscale)
+   *  and a non-square one is fitted into the square keeping its aspect. `size` above 192 warns
+   *  (Android 12+ shows only the inner 192 dp circle of the splash icon, the rest is cut; iOS and
+   *  Android before 12 show it whole), above 288 (the Android 12+ icon canvas) is refused.
+   *  Recommend a square mark: Android 12+ crops the splash icon to a circle. No image = the colour
+   *  alone. With the key, the generated files become CLI-owned (iOS: LaunchScreen.storyboard + the
+   *  LeCodesSplash imageset / LeCodesSplashBackground colorset; Android: the lecodes-runtime
+   *  module's res, through `Theme.LeCodesRuntime` — the parent the app's theme must name). Absent
+   *  = nothing is generated: the storyboard stays the person's, the Android window stays black. */
+  splash?: { background?: string, image?: string, size?: number }
   /** id → a spec for every platform (`"*"`, `"^2.0.0"`, `"github:owner/repo@v1"`, `"./plugins/<id>"`)
    *  or a spec per platform (`{ "web": "./plugins/ar-8thwall" }`; a platform it does not name is
    *  `"*"`). Read in the list form too (readAppConfigAt); a platform's spec is pluginSpecOf's. */
@@ -58,16 +73,28 @@ export interface AppConfig {
    *  / the "url" event — what `Browser.open(url, { returnUrl })` resolves on after an OAuth redirect.
    *  Lowercase letters, digits, `+ - .`, starting with a letter. */
   urlScheme?: string
+  /** The verified https links the shells open on (`"https://shop.example/pay/"`: a URL prefix,
+   *  several allowed): iOS universal links (`applinks:<host>` in the entitlements), Android App
+   *  Links (an `autoVerify` intent-filter per host, with the paths). A link reaches the app as
+   *  `app.launchUrl` / the "url" event — the return of `Browser.open(url, { returnUrl })` when
+   *  the page (a bank's app, a checkout) sends the person back by https. The site must serve the
+   *  two proofs (sync prints them): /.well-known/apple-app-site-association and
+   *  /.well-known/assetlinks.json. One list for both platforms, like `plugins`. */
+  appLinks?: string[]
   /** `remote`: lecodesignore-style globs of resources to STREAM from the server instead of
    *  embedding in the app (server-backed projects only — a streamed asset needs a server URL). */
   resources?: { remote?: string[] }
   /** Over-the-air JS updates: where the shell checks for newer compiled code at launch
-   *  (natively, before the JS engine — offline is a no-op, new code applies next launch).
+   *  (natively, before the JS engine — offline is a no-op). The first launch of an installed
+   *  build waits for the check (≤ 5 s, the splash held) and runs the newest bundle; every later
+   *  launch runs the local bundle at once and new code applies next launch.
    *  `true` = this project's live bundle on the platform (server-backed only); or an https
    *  URL to a compiled bundle on any hosting (string or `{ "url": … }`). Absent = no OTA.
    *  Both shells: iOS reads it from Info.plist (LeCodesUpdater), Android from the manifest
    *  meta-data the CLI-owned lecodes-runtime module carries (LeCodesShell.boot). A download runs
-   *  only when it is of the shell's SDK major and not older than the bundle running. */
+   *  only when it is of the shell's SDK major and not older than the bundle running; a store
+   *  update keeps a downloaded bundle only when it is newer code (by compile date) than the one
+   *  the update ships. */
   update?: boolean | string | { url?: string }
   /** `variant`: SDK product — "auto" (default: sync picks the smallest one covering the engines
    *  the compiled bundle actually uses) or core|2d|3d|full to force one.
@@ -229,6 +256,62 @@ export const urlSchemeOf = (config: Pick<AppConfig, "urlScheme"> | null | undefi
   return scheme
 }
 
+/** One app.json "appLinks" entry, parsed: the prefix as written, its host, its path ("" for the
+ *  host's root — every path of the host). */
+export interface AppLink { url: string, host: string, path: string }
+
+/** app.json "appLinks", checked: https URL prefixes with a host, no query / fragment (a prefix
+ *  ends at a path). Empty when the key is absent. */
+export const appLinksOf = (config: Pick<AppConfig, "appLinks"> | null | undefined): AppLink[] => {
+  const raw = config?.appLinks
+  if (raw === undefined) return []
+  if (!Array.isArray(raw)) throw new CliError(`app.json "appLinks" must be a list of https URL prefixes (["https://shop.example/pay/"]) — got ${JSON.stringify(raw)}.`)
+  const links: AppLink[] = []
+  for (const entry of raw) {
+    let url: URL
+    try { url = new URL(typeof entry === "string" ? entry : "") } catch { url = null as any }
+    if (!url || url.protocol !== "https:" || !url.hostname) {
+      throw new CliError(`app.json "appLinks": ${JSON.stringify(entry)} is not an https URL prefix ("https://shop.example/pay/"). A custom scheme goes in "urlScheme".`)
+    }
+    if (url.search || url.hash || url.username || url.port) {
+      throw new CliError(`app.json "appLinks": ${JSON.stringify(entry)} — a prefix is a host and a path, no query, fragment, port or credentials.`)
+    }
+    const path = url.pathname === "/" ? "" : url.pathname
+    if (links.some(l => l.host === url.hostname && l.path === path)) continue
+    links.push({ url: `https://${url.hostname}${path}`, host: url.hostname, path })
+  }
+  return links
+}
+
+/** The iOS entitlement "appLinks" means: one `applinks:<host>` per host (the paths live in the
+ *  site's apple-app-site-association). */
+export const associatedDomainsOf = (links: AppLink[]): string[] => [...new Set(links.map(l => `applinks:${l.host}`))]
+
+/** What the sites named by "appLinks" must serve for the OS to trust the links — printed by sync
+ *  so nobody composes them by hand: the AASA for iOS (`teamId.bundleId` + the paths), assetlinks
+ *  for Android (the package + the signing certificate's SHA-256, which `lecodes app keystore show`
+ *  prints). One block per host. */
+export const appLinksSiteNote = (links: AppLink[], ids: { platform: "ios", teamId?: string, bundleId?: string } | { platform: "android", applicationId?: string }): string[] => {
+  const lines: string[] = []
+  const hosts = [...new Set(links.map(l => l.host))]
+  for (const host of hosts) {
+    const paths = links.filter(l => l.host === host).map(l => l.path)
+    const patterns = paths.includes("") ? ["*"] : paths.map(p => `${p}*`)
+    if (ids.platform === "ios") {
+      const appId = `${ids.teamId ?? "<TEAM_ID>"}.${ids.bundleId ?? "<BUNDLE_ID>"}`
+      lines.push(`https://${host}/.well-known/apple-app-site-association (Content-Type: application/json, no redirect — Apple's CDN fetches it at install):`)
+      lines.push(JSON.stringify({ applinks: { details: [{ appIDs: [appId], components: patterns.map(p => ({ "/": p })) }] } }))
+    } else {
+      lines.push(`https://${host}/.well-known/assetlinks.json (Content-Type: application/json):`)
+      lines.push(JSON.stringify([{
+        relation: ["delegate_permission/common.handle_all_urls"],
+        target: { namespace: "android_app", package_name: ids.applicationId ?? "<APPLICATION_ID>", sha256_cert_fingerprints: ["<SHA-256 of the signing certificate — `lecodes app keystore show`>"] },
+      }]))
+    }
+  }
+  return lines
+}
+
 /** app.json wherever a command needs the project-level desktop/window config. Tolerant of a
  *  missing or broken file — standalone projects (no app.json) must keep working everywhere
  *  this is consulted. */