Document splash screen feature in project config, platform guides, and changelog

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: proggeramlug

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Detailed changelog for Perry. See CLAUDE.md for concise summaries.
 
+## v0.2.178
+- **Splash screen support for iOS and Android**
+  - Parse `perry.splash` config from `package.json` with three tiers: universal (single image + color), per-platform overrides, full custom file override
+  - iOS: auto-generate LaunchScreen.storyboard with centered image (128x128pt, scaleAspectFit) and custom background color; or use a custom storyboard
+  - Android: `Theme.Perry.Splash` style with `windowBackground` layer-list drawable; activity calls `setTheme()` in `onCreate` to switch to normal theme
+  - New template file: `perry-ui-android/template/app/src/main/res/drawable/splash_background.xml`
+  - Modified: `compile.rs` (iOS storyboard generation), `themes.xml`, `AndroidManifest.xml`, `PerryActivity.kt`
+
 ## v0.2.147
 - **Mark-sweep garbage collection** for bounded memory in long-running programs
   - New `crates/perry-runtime/src/gc.rs`: full GC infrastructure

docs/src/getting-started/project-config.md

@@ -48,6 +48,80 @@ When a package is listed here, Perry:
 
 This is useful for pure TypeScript/JavaScript packages that don't rely on Node.js APIs. Packages that use native bindings, `eval()`, or dynamic `require()` won't work.
 
+#### `splash`
+
+Configure a native splash screen for iOS and Android. The splash screen appears instantly during cold start, before your app code runs.
+
+**Minimal (both platforms share the same splash):**
+
+```json
+{
+  "perry": {
+    "splash": {
+      "image": "logo/icon-256.png",
+      "background": "#FFF5EE"
+    }
+  }
+}
+```
+
+**Per-platform overrides:**
+
+```json
+{
+  "perry": {
+    "splash": {
+      "image": "logo/icon-256.png",
+      "background": "#FFF5EE",
+      "ios": {
+        "image": "logo/splash-ios.png",
+        "background": "#FFFFFF"
+      },
+      "android": {
+        "image": "logo/splash-android.png",
+        "background": "#FFFFFF"
+      }
+    }
+  }
+}
+```
+
+**Full custom override (complete control):**
+
+```json
+{
+  "perry": {
+    "splash": {
+      "ios": {
+        "storyboard": "splash/LaunchScreen.storyboard"
+      },
+      "android": {
+        "layout": "splash/splash_background.xml",
+        "theme": "splash/themes.xml"
+      }
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `splash.image` | Path to a PNG image, centered on the splash screen (both platforms) |
+| `splash.background` | Hex color for the background (default: `#FFFFFF`) |
+| `splash.ios.image` | iOS-specific image override |
+| `splash.ios.background` | iOS-specific background color |
+| `splash.ios.storyboard` | Custom LaunchScreen.storyboard (compiled with ibtool) |
+| `splash.android.image` | Android-specific image override |
+| `splash.android.background` | Android-specific background color |
+| `splash.android.layout` | Custom drawable XML for `windowBackground` |
+| `splash.android.theme` | Custom themes.xml |
+
+**Resolution order** per platform:
+1. Custom file override (storyboard / layout+theme)
+2. Platform-specific image/color (`splash.{platform}.image`)
+3. Universal image/color (`splash.image`)
+4. No `splash` key → blank white screen (backward compatible)
+
 ## Using npm Packages
 
 Perry natively supports many popular npm packages without any configuration:

docs/src/platforms/android.md

@@ -48,6 +48,40 @@ Perry maps UI widgets to Android views via JNI:
 - **Alerts**: `PerryBridge.showAlert`
 - **Sheets**: Dialog (modal)
 
+## Splash Screen
+
+Perry's Android template includes a splash theme (`Theme.Perry.Splash`) that displays a `windowBackground` drawable during cold start. Configure it via `perry.splash` in `package.json`:
+
+```json
+{
+  "perry": {
+    "splash": {
+      "image": "logo/icon-256.png",
+      "background": "#FFF5EE"
+    }
+  }
+}
+```
+
+The image is centered via a `layer-list` drawable with a solid background color. The activity switches to the normal theme in `onCreate` before inflating the layout, so the splash disappears as soon as the app is ready.
+
+For full control, provide custom drawable and theme XML files:
+
+```json
+{
+  "perry": {
+    "splash": {
+      "android": {
+        "layout": "splash/splash_background.xml",
+        "theme": "splash/themes.xml"
+      }
+    }
+  }
+}
+```
+
+See [Project Configuration](../getting-started/project-config.md#splash) for the full config reference.
+
 ## Differences from Desktop
 
 - **Touch-only**: No hover events, no right-click context menus

docs/src/platforms/ios.md

@@ -70,6 +70,35 @@ perry widget.ts --target ios-widget
 
 See [Widgets (WidgetKit)](../widgets/overview.md) for details.
 
+## Splash Screen
+
+Perry auto-generates a native `LaunchScreen.storyboard` from the `perry.splash` config in `package.json`. The splash screen appears instantly during cold start.
+
+```json
+{
+  "perry": {
+    "splash": {
+      "image": "logo/icon-256.png",
+      "background": "#FFF5EE"
+    }
+  }
+}
+```
+
+The image is centered at 128x128pt with `scaleAspectFit`. You can provide a custom storyboard for full control:
+
+```json
+{
+  "perry": {
+    "splash": {
+      "ios": { "storyboard": "splash/LaunchScreen.storyboard" }
+    }
+  }
+}
+```
+
+See [Project Configuration](../getting-started/project-config.md#splash) for the full config reference.
+
 ## Differences from macOS
 
 - **No menu bar**: iOS doesn't support menu bars. Use toolbar or navigation patterns.