lecodes-cli 2.4.2 → 2.4.4

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,30 @@ 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 — a 304 when
+   *  the source is not newer than the build (If-Modified-Since from the embedded bundle's compile
+   *  date: nothing downloaded, the embedded bundle runs); 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 +258,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. */

package/src/commands/app/splash.ts

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import type { JimpInstance } from "jimp"
+import { Color } from "lecodes-sdk/color"
+import { CliError, c, log, warn } from "../../cli"
+import type { AppConfig } from "./shared"
+import { splashStoryboardTemplate } from "./templates/ios"
+import {
+  SPLASH_ICON_CANVAS_DP, runtimeThemeTemplate, runtimeThemeV31Template, splashIconTemplate, splashWindowTemplate,
+  type AndroidSplashResources,
+} from "./templates/android"
+
+/* The launch screen rendered from app.json "splash": { "background"?, "image"?, "size"? } — the
+ * colour and an optional mark fitted CENTRED into a fixed logical square, 160 pt / dp unless "size"
+ * says otherwise, on both shells (docs/plans/ota-splash-plan.md R6), every density rendered from the one master the way icon.ts renders the icons. The ownership
+ * rule is icon's: without the key sync never touches a launch-screen file (the storyboard stays the
+ * person's; removing the key later stops regeneration and deletes nothing); with it, these become
+ * CLI-owned:
+ *   ios/App/Base.lproj/LaunchScreen.storyboard
+ *   ios/App/Assets.xcassets/LeCodesSplashBackground.colorset/ + LeCodesSplash.imageset/
+ * On Android the resources live in the CLI-owned lecodes-runtime module, regenerated whole every
+ * sync — Theme.LeCodesRuntime is written with or without the key (black without), the app's
+ * user-owned Theme.LeCodesApp inherits it. jimp is imported lazily, as in icon.ts. */
+
+/** The side of the square the mark is fitted into, pt on iOS and dp on Android, when app.json
+ *  "splash" names no "size". */
+export const SPLASH_DEFAULT_SIZE = 160
+
+/** Android 12+ shows only this circle of its 288 dp splash-icon canvas (SPLASH_ICON_CANVAS_DP): a
+ *  larger mark loses its corners / edges there — iOS and Android before 12 show it whole. */
+const SPLASH_VISIBLE_CIRCLE_DP = 192
+
+const IOS_SCALES = [1, 2, 3] as const
+
+const ANDROID_DENSITIES = [
+  { qualifier: "mdpi", scale: 1 },
+  { qualifier: "hdpi", scale: 1.5 },
+  { qualifier: "xhdpi", scale: 2 },
+  { qualifier: "xxhdpi", scale: 3 },
+  { qualifier: "xxxhdpi", scale: 4 },
+] as const
+
+export interface SplashMaster {
+  /** The decoded master (straight alpha), any shape; null = colour only. */
+  image: JimpInstance | null
+  /** The side of the square the image is fitted into, pt / dp (SPLASH_DEFAULT_SIZE by default). */
+  size: number
+  /** 0xRRGGBB. */
+  rgb: number
+  /** "#RRGGBB" for resource files. */
+  backgroundHex: string
+}
+
+/** app.json "splash" resolved, or null when the key is absent (nothing is generated then). */
+export const loadSplashMaster = async (root: string, config: AppConfig): Promise<SplashMaster | null> => {
+  const splash = config.splash
+  if (splash === undefined) return null
+  if (splash === null || typeof splash !== "object" || Array.isArray(splash)) {
+    throw new CliError(`app.json "splash" must be an object — { "background"?: "#RRGGBB", "image"?: "./splash.png" } (got ${JSON.stringify(splash)})`)
+  }
+
+  // Any CSS color, opaque (a launch screen has nothing behind it): the SDK's one parser, as for
+  // the icon backdrop — which is also the default.
+  const [given, from] = splash.background !== undefined
+    ? [splash.background, "splash.background"]
+    : [config.iconBackground ?? "#FFFFFF", "iconBackground"]
+  const rgba = Color.tryParse(given)
+  if (!rgba || (Color.toPackedRgba(rgba) & 0xff) !== 0xff) {
+    throw new CliError(`app.json "${from}" (the splash colour) must be an opaque CSS color — #RRGGBB, a name, rgb() / hsl() (got ${JSON.stringify(given)})`)
+  }
+  const rgb = Color.toPackedRgb(rgba)
+  const backgroundHex = "#" + rgb.toString(16).padStart(6, "0").toUpperCase()
+
+  // The logical side: past the 288 dp canvas the Android 12+ inset would go negative; past the
+  // 192 dp circle the system cuts the mark there.
+  const size = splash.size ?? SPLASH_DEFAULT_SIZE
+  if (typeof size !== "number" || !Number.isInteger(size) || size <= 0) {
+    throw new CliError(`app.json "splash.size" must be a positive whole number of pt / dp (got ${JSON.stringify(splash.size)})`)
+  }
+  if (size > SPLASH_ICON_CANVAS_DP) {
+    throw new CliError(`app.json "splash.size" is at most ${SPLASH_ICON_CANVAS_DP} — the Android 12+ splash-icon canvas (got ${size})`)
+  }
+  if (size > SPLASH_VISIBLE_CIRCLE_DP) {
+    warn(`"splash.size" ${size} is over ${SPLASH_VISIBLE_CIRCLE_DP}: Android 12+ shows only the inner ${SPLASH_VISIBLE_CIRCLE_DP} dp circle of the splash icon, so the image's corners / edges beyond it are cut (iOS and Android before 12 show it whole).`)
+  }
+
+  if (splash.image === undefined) return { image: null, size, rgb, backgroundHex }
+  if (typeof splash.image !== "string" || !splash.image) {
+    throw new CliError(`app.json "splash.image" must be a project-root-relative path to a PNG / JPEG (got ${JSON.stringify(splash.image)})`)
+  }
+  const rel = splash.image
+  const path = resolve(root, rel)
+  if (!existsSync(path)) throw new CliError(`app.json "splash.image": ${rel} not found`)
+  const { Jimp } = await import("jimp")
+  let image: JimpInstance
+  try {
+    image = (await Jimp.read(path)) as JimpInstance
+  } catch (e) {
+    throw new CliError(`Could not decode "splash.image" ${rel} (${(e as Error).message}) — use a PNG or JPEG.`)
+  }
+  // Under 3 × size the iOS @3x / Android xxhdpi renderings are an upscale. xxxhdpi (4 × size)
+  // upscales a master between the two a little; that is accepted, no warning.
+  const minPx = 3 * size
+  if (Math.max(image.width, image.height) < minPx) {
+    warn(`"splash.image" ${rel} is ${image.width}×${image.height} — under ${minPx}px (3 × "size" ${size}), so the @3x / xxhdpi renderings are upscaled and may look soft.`)
+  }
+  return { image, size, rgb, backgroundHex }
+}
+
+/** The master fitted into a transparent px×px square, centred, aspect kept — every rendering is
+ *  square, so the size×size frame on both platforms never stretches it. */
+const renderSquare = async (master: JimpInstance, px: number): Promise<Buffer> => {
+  const { Jimp } = await import("jimp")
+  const canvas = new Jimp({ width: px, height: px, color: 0x00000000 })
+  const f = px / Math.max(master.width, master.height)
+  const w = Math.max(1, Math.round(master.width * f))
+  const h = Math.max(1, Math.round(master.height * f))
+  const fitted = master.clone() as JimpInstance
+  fitted.resize({ w, h })
+  canvas.composite(fitted, Math.round((px - w) / 2), Math.round((px - h) / 2))
+  return canvas.getBuffer("image/png")
+}
+
+const writeFile = (abs: string, content: Uint8Array | string) => {
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, content)
+}
+
+/* ------------------------------------------ iOS ------------------------------------------ */
+
+const hex2 = (v: number) => "0x" + v.toString(16).padStart(2, "0").toUpperCase()
+
+const colorsetJson = (rgb: number): string => `{
+  "colors" : [
+    {
+      "color" : {
+        "color-space" : "srgb",
+        "components" : {
+          "alpha" : "1.000",
+          "blue" : "${hex2(rgb & 0xff)}",
+          "green" : "${hex2((rgb >> 8) & 0xff)}",
+          "red" : "${hex2((rgb >> 16) & 0xff)}"
+        }
+      },
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
+`
+
+const IMAGESET_JSON = `{
+  "images" : [
+${IOS_SCALES.map(s => `    {
+      "filename" : "LeCodesSplash${s === 1 ? "" : `@${s}x`}.png",
+      "idiom" : "universal",
+      "scale" : "${s}x"
+    }`).join(",\n")}
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
+`
+
+/** The launch storyboard + its colorset / imageset. Null = app.json has no "splash": nothing is
+ *  touched. Without an image the imageset a previous sync wrote is removed (it is CLI-owned). */
+export const writeIosSplash = async (iosDir: string, master: SplashMaster | null): Promise<void> => {
+  if (!master) return
+  const assets = join(iosDir, "App", "Assets.xcassets")
+  writeFile(join(assets, "LeCodesSplashBackground.colorset", "Contents.json"), colorsetJson(master.rgb))
+  const imageset = join(assets, "LeCodesSplash.imageset")
+  if (master.image) {
+    for (const s of IOS_SCALES) {
+      writeFile(join(imageset, `LeCodesSplash${s === 1 ? "" : `@${s}x`}.png`), await renderSquare(master.image, master.size * s))
+    }
+    writeFile(join(imageset, "Contents.json"), IMAGESET_JSON)
+  } else {
+    rmSync(imageset, { recursive: true, force: true })
+  }
+  writeFile(join(iosDir, "App", "Base.lproj", "LaunchScreen.storyboard"), splashStoryboardTemplate(!!master.image, master.rgb, master.size))
+  log(`${c.green("splash")}    ${master.backgroundHex}${master.image ? ` + the image at ${master.size} pt (@1x/@2x/@3x)` : ""} → ios/App/Base.lproj/LaunchScreen.storyboard`)
+}
+
+/* ---------------------------------------- Android ---------------------------------------- */
+
+/** The splash resources of the runtime module; every one of them is removed when it has no
+ *  place (no key, no image), so a stale one never outlives its app.json value. */
+const ANDROID_SPLASH_FILES = {
+  v31: join("values-v31", "lecodes_splash.xml"),
+  window: join("drawable", "lecodes_splash_window.xml"),
+  icon: join("drawable", "lecodes_splash_icon.xml"),
+  png: (qualifier: string) => join(`drawable-${qualifier}`, "lecodes_splash.png"),
+}
+
+/** lecodes-runtime/src/main/res: Theme.LeCodesRuntime always (black without the key), and with a
+ *  master the colour, the layer-list window background, the v31 system splash and the densities. */
+export const writeAndroidSplash = async (androidDir: string, master: SplashMaster | null): Promise<void> => {
+  const resDir = join(androidDir, "lecodes-runtime", "src", "main", "res")
+  const res: AndroidSplashResources | undefined = master ? { backgroundHex: master.backgroundHex, image: !!master.image, size: master.size } : undefined
+  writeFile(join(resDir, "values", "lecodes_splash.xml"), runtimeThemeTemplate(res))
+  const drop = (rel: string) => rmSync(join(resDir, rel), { force: true })
+
+  if (!res) {
+    drop(ANDROID_SPLASH_FILES.v31)
+    drop(ANDROID_SPLASH_FILES.window)
+  } else {
+    writeFile(join(resDir, ANDROID_SPLASH_FILES.v31), runtimeThemeV31Template(res))
+    writeFile(join(resDir, ANDROID_SPLASH_FILES.window), splashWindowTemplate(res))
+  }
+  if (master?.image) {
+    for (const { qualifier, scale } of ANDROID_DENSITIES) {
+      writeFile(join(resDir, ANDROID_SPLASH_FILES.png(qualifier)), await renderSquare(master.image, Math.round(master.size * scale)))
+    }
+    writeFile(join(resDir, ANDROID_SPLASH_FILES.icon), splashIconTemplate(master.size))
+  } else {
+    for (const { qualifier } of ANDROID_DENSITIES) drop(ANDROID_SPLASH_FILES.png(qualifier))
+    drop(ANDROID_SPLASH_FILES.icon)
+  }
+  if (master) {
+    log(`${c.green("splash")}    ${master.backgroundHex}${master.image ? ` + the image at ${master.size} dp (mdpi…xxxhdpi)` : ""} → android/lecodes-runtime/src/main/res/ (Theme.LeCodesRuntime)`)
+  }
+}
+
+/** The edit an app's USER-owned theme needs for the splash to show, or null when it inherits
+ *  Theme.LeCodesRuntime already (and sets no window background of its own over it). Read by sync
+ *  (a warning, when "splash" is set) and doctor. */
+export const androidSplashThemeHint = (androidDir: string): string | null => {
+  const path = join(androidDir, "app", "src", "main", "res", "values", "themes.xml")
+  if (!existsSync(path)) return null
+  const xml = readFileSync(path, "utf8")
+  // The init template's theme; a person who renamed it is taken at their word when some style of
+  // the file inherits the runtime theme.
+  const style = /<style\b[^>]*\bname="Theme\.LeCodesApp"[^>]*?(?:\/>|>([\s\S]*?)<\/style>)/.exec(xml)
+  if (!style) {
+    return /\bparent="Theme\.LeCodesRuntime"/.test(xml) ? null
+      : `app/src/main/res/values/themes.xml: the app's theme needs parent="Theme.LeCodesRuntime" and no android:windowBackground of its own for the splash to show — see "Splash screen" in android/README.md`
+  }
+  const inherits = /\bparent="Theme\.LeCodesRuntime"/.test(style[0].slice(0, style[0].indexOf(">") + 1))
+  const ownBackground = /name="android:windowBackground"/.test(style[1] ?? "")
+  if (inherits && !ownBackground) return null
+  const edits = [
+    !inherits && `parent="Theme.LeCodesRuntime"`,
+    ownBackground && `no android:windowBackground item`,
+  ].filter(Boolean).join(" and ")
+  return `app/src/main/res/values/themes.xml: give Theme.LeCodesApp ${edits} — the splash is drawn by that theme (see "Splash screen" in android/README.md)`
+}

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>
 `