lecodes-cli 2.4.1 → 2.4.3

package/src/commands/app/shared.ts

@@ -1,13 +1,13 @@
 import { execFileSync } from "node:child_process"
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
-import { dirname, join, resolve } from "node:path"
+import { basename, dirname, join, resolve } from "node:path"
 import { findProjectRoot, readManifest, type Manifest } from "../../project/manifest"
 import { loadConfig, requireApiUrl } from "../../platform/config"
 import { DEFAULT_IGNORE_FILE } from "../../project/ignore"
 import { CliError, c, log, note, warn } from "../../cli"
 import { pascal, readManifest as readPluginManifest, type IosPackage, type PluginManifest as PluginManifest2 } from "../../plugin/manifest"
-import { pluginSpecsOf } from "lecodes-sdk/compile"
+import { PLUGIN_PLATFORMS, isLocalPluginSpec, pluginEntriesOf, pluginSpecOf, type PluginEntry } from "lecodes-sdk/compile"
 
 /** The 2.x manifest (plugin/manifest.ts), plus the desktop branch the desktop flow reads: a
  *  PREBUILT shared library per OS/arch behind the C ABI in hosts/desktop/plugin-sdk — another
@@ -23,7 +23,12 @@ export type PluginManifest = PluginManifest2 & { desktop?: { library?: Record<st
 /** First-party plugin registry: id → GitHub repo holding plugins/<id>/. Third-party plugins
  *  use a `github:owner/repo[@tag]` spec in app.json instead (manifest at the repo root); a plugin
  *  of the project itself a PATH (`./plugins/<id>` — the folder with its lecodes-plugin.json,
- *  generated by `lecodes plugin gen`; nothing to publish). */
+ *  generated by `lecodes plugin gen`; nothing to publish).
+ *  What a SHELL can vendor: the plugins of the repo's released v* tags (a sync checks out the
+ *  newest). The newer first-party plugins (ar, speech, audio-recorder, webrtc) are in the viewers
+ *  and in the SDK, and in no tag yet — an id joins this list with the tag that carries it; listing
+ *  one before would make `app sync` clone a tag without its folder. compile, link and the web
+ *  builds never read this list (the header lists app.json's keys; the web halves are Web Lite's). */
 export const FIRST_PARTY_PLUGINS: Record<string, string> = {
   "camera": "letary/lecodes-plugins",
   "qr-scanner": "letary/lecodes-plugins",
@@ -44,22 +49,52 @@ 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
-  plugins?: Record<string, 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. */
+  plugins?: Record<string, PluginEntry>
   /** The custom URL scheme the shells open on (`myshop` → `myshop://…`): iOS CFBundleURLTypes,
    *  Android a BROWSABLE intent-filter on the activity. A link reaches the app as `app.launchUrl`
    *  / 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.
@@ -221,17 +256,94 @@ 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. */
 export const readAppConfigAt = (root: string): AppConfig | null => {
   const config = readJson<AppConfig & { plugins?: unknown }>(join(root, "app.json"))
-  // `"plugins"` is read in either shape (`["camera"]` or `{ "camera": "*" }`, the SDK's rule):
-  // every command below works on id → spec, and a list read as "no plugins" vendored nothing.
-  if (config && "plugins" in config) config.plugins = pluginSpecsOf(config.plugins)
+  // `"plugins"` is read in any shape (`["camera"]`, `{ "camera": "*" }`, `{ "ar": { "web": … } }`,
+  // the SDK's rule): every command below works on id → entry, and a list read as "no plugins"
+  // vendored nothing. An entry of no shape is refused here, by its key — the SDK reads it as "*".
+  if (config && "plugins" in config) {
+    checkPluginEntries(config.plugins)
+    config.plugins = pluginEntriesOf(config.plugins)
+  }
   return config as AppConfig | null
 }
 
+const SPEC_WORDS = `a spec ("*", "^2.0.0", "github:owner/repo[@tag]", "./plugins/<id>") or a spec per platform ({ ${PLUGIN_PLATFORMS.map((p) => `"${p}"`).join(", ")} } → spec; a platform not named is "*")`
+
+const checkPluginEntries = (plugins: unknown): void => {
+  if (plugins === undefined || Array.isArray(plugins)) return
+  if (!plugins || typeof plugins !== "object") throw new CliError(`app.json "plugins": a list of ids, or id → ${SPEC_WORDS}.`)
+  for (const [id, value] of Object.entries(plugins as Record<string, unknown>)) {
+    if (typeof value === "string" && value.trim() !== "") continue
+    const ok = !!value && typeof value === "object" && !Array.isArray(value) &&
+      Object.entries(value as Record<string, unknown>).every(([p, s]) => (PLUGIN_PLATFORMS as readonly string[]).includes(p) && typeof s === "string" && s.trim() !== "")
+    if (!ok) throw new CliError(`app.json "plugins"."${id}": ${SPEC_WORDS} — got ${JSON.stringify(value)}.`)
+  }
+}
+
+/** app.json's plugins as one platform takes them: id → that platform's spec. */
+export const pluginSpecsFor = (config: Pick<AppConfig, "plugins"> | null | undefined, platform: PluginPlatform): [string, string][] =>
+  Object.entries(config?.plugins ?? {}).map(([id, entry]) => [id, pluginSpecOf(entry, platform)])
+
 /** The desktop host's own built-in fallback, mirrored where the CLI must fill a missing side. */
 export const DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 }
 
@@ -278,10 +390,6 @@ export type { IosPackage }
 
 export interface LockEntry { repo: string, tag: string, commit: string, version: string }
 
-/** A plugin spec that names a folder of the project (`./plugins/x`, `../x`, `/abs`, `file:x`). */
-export const isLocalPluginSpec = (spec: string): boolean =>
-  spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || spec.startsWith("file:")
-
 /** Resolve app.json "update" to the URL a shell's native updater checks (LeCodesUpdater on both
  *  platforms): absent or `true` = the project's live bundle on the platform —
  *  `/code/<uuid>.js?sdk=<version>`, the launcher's own URL, so a pushed project updates its shells
@@ -548,18 +656,43 @@ export const ensureRepo = (repo: string, wantTag: string | null, lock: LockEntry
 
 /** Resolve one app.json plugin entry to vendorable sources + manifest + lock pin. The platform
  *  being synced must be supported (its manifest branch non-null) — a hard error otherwise. */
-export type PluginPlatform = "ios" | "android" | "desktop"
-const PLUGIN_PLATFORM_LABEL: Record<PluginPlatform, string> = { ios: "iOS", android: "Android", desktop: "desktop" }
+export type PluginPlatform = "ios" | "android" | "desktop" | "web"
+const PLUGIN_PLATFORM_LABEL: Record<PluginPlatform, string> = { ios: "iOS", android: "Android", desktop: "desktop", web: "the web" }
+
+/** A plugin of the project itself (a local spec): its folder and its manifest. The key of app.json
+ *  is the plugin's id: the folder's own (`"acme-dial": "./plugins/acme-dial"`), or — for a HALF
+ *  FOLDER — the first-party plugin it implements (`"ar": { "web": "./plugins/ar-8thwall" }`). */
+export const localPlugin = (root: string, id: string, spec: string): { dir: string, manifest: PluginManifest } => {
+  const dir = resolve(root, spec.startsWith("file:") ? spec.slice("file:".length) : spec)
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new CliError(`Plugin "${id}": ${spec} is not a folder (${dir})`)
+  const folder = basename(dir)
+  const manifest: PluginManifest = readPluginManifest(dir, folder)
+  if (manifest.implements ? manifest.implements !== id : folder !== id) {
+    throw new CliError(manifest.implements
+      ? `Plugin "${id}": ${spec} implements "${manifest.implements}" — app.json names it under that plugin: "${manifest.implements}": { "<platform>": "${spec}" }`
+      : `Plugin "${id}": ${spec} is the plugin "${folder}" — app.json names a plugin of the project by its folder's name`)
+  }
+  fillManifestDefaults(manifest, folder)
+  return { dir, manifest }
+}
+
+/** The key app.json names a local plugin under: its folder's name, or the first-party plugin a half
+ *  folder implements. */
+export const localPluginKey = (root: string, spec: string): string => {
+  const dir = resolve(root, spec.startsWith("file:") ? spec.slice("file:".length) : spec)
+  if (!existsSync(join(dir, "lecodes-plugin.json"))) return basename(dir)
+  return readPluginManifest(dir, basename(dir)).implements ?? basename(dir)
+}
 
-export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform): ResolvedPlugin
-export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts: { optional: true }): ResolvedPlugin | null
-export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts?: { optional?: boolean }): ResolvedPlugin | null {
+/** `entry` is app.json's for the id, in either form: the platform's own spec is resolved (a
+ *  per-platform entry that does not name the platform is the first-party plugin, `"*"`). */
+export function resolvePlugin(id: string, entry: PluginEntry, lock: LockEntry | undefined, platform: PluginPlatform): ResolvedPlugin
+export function resolvePlugin(id: string, entry: PluginEntry, lock: LockEntry | undefined, platform: PluginPlatform, opts: { optional: true }): ResolvedPlugin | null
+export function resolvePlugin(id: string, entry: PluginEntry, lock: LockEntry | undefined, platform: PluginPlatform, opts?: { optional?: boolean }): ResolvedPlugin | null {
+  const spec = pluginSpecOf(entry, platform)
   // A plugin of the project itself: its folder, as it is — no clone, no tag, nothing to publish.
   if (isLocalPluginSpec(spec)) {
-    const dir = resolve(projectRoot(), spec.startsWith("file:") ? spec.slice("file:".length) : spec)
-    if (!existsSync(dir)) throw new CliError(`Plugin "${id}": ${spec} is not a folder (${dir})`)
-    const manifest: PluginManifest = readPluginManifest(dir, id)
-    fillManifestDefaults(manifest, id)
+    const { dir, manifest } = localPlugin(projectRoot(), id, spec)
     if (!manifest[platform]) {
       if (opts?.optional) return null
       throw new CliError(`Plugin "${id}" does not support ${PLUGIN_PLATFORM_LABEL[platform]} (manifest "${platform}" is null)`)
@@ -640,8 +773,8 @@ export const desktopPluginLibraries = (root: string, opts: { strict?: boolean }
     dirs.push(local)
     for (const f of readdirSync(local)) if (isDesktopPluginLibrary(f)) files.push(join(local, f))
   }
-  const config = readJson<AppConfig>(join(root, "app.json"))
-  const specs = Object.entries(config?.plugins ?? {})
+  const config = readJson<{ plugins?: unknown }>(join(root, "app.json"))
+  const specs = pluginSpecsFor({ plugins: pluginEntriesOf(config?.plugins) }, "desktop")
   if (specs.length === 0) return { dirs, files }
   const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
   const target = desktopPluginTarget()

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)`
+}