fix: single-query listApps

docs: add wallpaper transparency and hyperos-4 soft-glass style
feat: app repository for list and launch apps
2026-08-16 16:12:44 +08:00 · 2026-08-16 16:09:21 +08:00 · 2026-08-16 16:08:37 +08:00 · 2026-08-16 16:01:36 +08:00 · 2026-08-16 16:01:36 +08:00 · 2026-08-16 15:34:45 +08:00
20 changed files with 2479 additions and 0 deletions
@@ -0,0 +1,13 @@
+# Superpowers brainstorm mockups / session state
+.superpowers/
+
+# Android 本地 SDK 路径
+local.properties
+
+# Gradle 构建产物
+.gradle/
+build/
+app/build/
+.idea/
+*.iml
+.kotlin/
@@ -0,0 +1,27 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+android {
+    namespace = "top.yeij.hearth"
+    compileSdk = 35
+    defaultConfig {
+        applicationId = "top.yeij.hearth"
+        minSdk = 30
+        targetSdk = 30
+        versionCode = 1
+        versionName = "0.1.0"
+    }
+    buildTypes { release { isMinifyEnabled = false } }
+    compileOptions { sourceCompatibility = JavaVersion.VERSION_17; targetCompatibility = JavaVersion.VERSION_17 }
+    kotlinOptions { jvmTarget = "17" }
+    // 本地单元测试中 android.* 桩方法返回默认值（避免 Log.d 抛 "not mocked"）
+    // android.* stub methods return default values in local unit tests (avoid Log.d "not mocked")
+    testOptions { unitTests { isReturnDefaultValues = true } }
+}
+dependencies {
+    implementation("androidx.core:core-ktx:1.13.1")
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+    implementation("com.google.code.gson:gson:2.11.0")
+    testImplementation("junit:junit:4.13.2")
+}
@@ -0,0 +1,18 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
+    <application
+        android:label="Hearth"
+        android:theme="@android:style/Theme.Material.NoActionBar">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:screenOrientation="landscape">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.HOME" />
+                <category android:name="android.intent.category.DEFAULT" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Hearth</title>
+</head>
+<body>
+    <h1>Hearth Launcher</h1>
+    <p>占位页面，后续由 WebView 加载。</p>
+</body>
+</html>
@@ -0,0 +1,65 @@
+package top.yeij.hearth
+
+import android.app.Activity
+import android.content.res.Configuration
+import android.os.Bundle
+import android.util.Log
+import android.view.WindowInsets
+import android.view.WindowInsetsController
+import top.yeij.hearth.webview.JsBridge
+import top.yeij.hearth.webview.WebViewManager
+
+// HOME 桌面 activity，后续 Task 挂载 WebView 与 JsBridge
+// HOME launcher activity; later tasks mount WebView and JsBridge
+class MainActivity : Activity() {
+
+    companion object {
+        private const val TAG = "HearthMainActivity"
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        Log.d(TAG, "onCreate: enter immersive mode")
+        enterImmersive()
+        setupWebView()
+    }
+
+    // 创建 JsBridge 并挂载 WebView 桌面层
+    // Create JsBridge and mount the WebView launcher layer
+    private fun setupWebView() {
+        val dm = resources.displayMetrics
+        val darkMode =
+            (resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) ==
+                Configuration.UI_MODE_NIGHT_YES
+        val bridge = JsBridge(
+            deviceWidthPx = dm.widthPixels,
+            deviceHeightPx = dm.heightPixels,
+            density = dm.density,
+            darkMode = darkMode,
+        )
+        WebViewManager(this).attach(bridge)
+        Log.d(
+            TAG,
+            "setupWebView: attached WebView ${dm.widthPixels}x${dm.heightPixels}" +
+                " density=${dm.density} darkMode=$darkMode"
+        )
+    }
+
+    // 进入沉浸式全屏：隐藏状态栏与导航栏，滑动可临时唤出
+    // Enter immersive fullscreen: hide status/navigation bars, swipe to reveal transiently
+    private fun enterImmersive() {
+        window.insetsController?.let { ctrl ->
+            ctrl.hide(WindowInsets.Type.statusBars() or WindowInsets.Type.navigationBars())
+            ctrl.systemBarsBehavior =
+                WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        }
+    }
+
+    // Back 键桌面态屏蔽（webAPP 打开时由 WebAppContainer 接管）
+    // Swallow Back key on desktop state (WebAppContainer takes over when a webAPP is open)
+    @Suppress("DEPRECATION")
+    override fun onBackPressed() {
+        // 桌面态：吞掉，不响应
+        // Desktop state: consume the event, do not respond
+    }
+}
@@ -0,0 +1,42 @@
+package top.yeij.hearth.app
+
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+
+data class AppInfo(val packageName: String, val label: String, val iconBase64: String?)
+
+interface AppSource {
+    fun queryLaunchableApps(): List<AppInfo>
+    fun launch(packageName: String): Boolean
+}
+
+class AndroidAppSource(private val context: Context) : AppSource {
+    override fun queryLaunchableApps(): List<AppInfo> {
+        val pm = context.packageManager
+        val intent = Intent(Intent.ACTION_MAIN).addCategory(Intent.CATEGORY_LAUNCHER)
+        return pm.queryIntentActivities(intent, 0).map { ri ->
+            val pkg = ri.activityInfo.packageName
+            AppInfo(pkg, ri.loadLabel(pm).toString(), null /* 图标 base64 在 Task 5 补 */)
+        }
+    }
+
+    override fun launch(packageName: String): Boolean {
+        val i = context.packageManager.getLaunchIntentForPackage(packageName) ?: return false
+        i.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        context.startActivity(i)
+        return true
+    }
+}
+
+class AppRepository(private val source: AppSource) {
+    private val gson = com.google.gson.Gson()
+
+    fun listApps(): String {
+        val apps = source.queryLaunchableApps()
+        Log.d("HearthBridge", "listApps: ${apps.size} apps")
+        return gson.toJson(apps)
+    }
+
+    fun launchApp(packageName: String): Boolean = source.launch(packageName)
+}
@@ -0,0 +1,25 @@
+package top.yeij.hearth.webview
+
+import android.util.Log
+
+class JsBridge(
+    private val deviceWidthPx: Int,
+    private val deviceHeightPx: Int,
+    private val density: Float,
+    private val darkMode: Boolean,
+) {
+    private val gson = com.google.gson.Gson()
+
+    @android.webkit.JavascriptInterface
+    fun getDeviceInfo(): String {
+        Log.d("HearthBridge", "getDeviceInfo called")
+        return gson.toJson(
+            mapOf(
+                "widthPx" to deviceWidthPx,
+                "heightPx" to deviceHeightPx,
+                "density" to density,
+                "darkMode" to darkMode
+            )
+        )
+    }
+}
@@ -0,0 +1,26 @@
+package top.yeij.hearth.webview
+
+import android.annotation.SuppressLint
+import android.app.Activity
+import android.webkit.WebView
+import android.webkit.WebSettings
+import android.webkit.WebViewClient
+
+class WebViewManager(private val activity: Activity) {
+    @SuppressLint("SetJavaScriptEnabled")
+    fun attach(bridge: JsBridge): WebView {
+        val webView = WebView(activity)
+        webView.settings.apply {
+            javaScriptEnabled = true
+            useWideViewPort = true
+            loadWithOverviewMode = true
+            setSupportZoom(false)
+            domStorageEnabled = true
+        }
+        webView.addJavascriptInterface(bridge, "HearthBridge")
+        webView.webViewClient = WebViewClient()
+        webView.loadUrl("file:///android_asset/h5/index.html")
+        activity.setContentView(webView)
+        return webView
+    }
+}
@@ -0,0 +1,21 @@
+package top.yeij.hearth.app
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class AppRepositoryTest {
+    @Test
+    fun listApps_returnsLauncherAppsJson() {
+        val repo = AppRepository(FakeAppSource(listOf(FakeApp("com.x.music", "音乐"))))
+        val json = repo.listApps()
+        assertTrue(json.contains("\"packageName\":\"com.x.music\""))
+        assertTrue(json.contains("\"label\":\"音乐\""))
+    }
+
+    @Test
+    fun launchApp_unknownPackage_returnsFalse() {
+        val repo = AppRepository(FakeAppSource(emptyList()))
+        assertEquals(false, repo.launchApp("com.nope"))
+    }
+}
@@ -0,0 +1,13 @@
+package top.yeij.hearth.app
+
+// 测试用假源：返回固定应用列表，避免依赖 Android Context/PackageManager
+// Test fake source: returns a fixed app list, avoiding dependency on Android Context/PackageManager
+class FakeAppSource(private val apps: List<AppInfo>) : AppSource {
+    override fun queryLaunchableApps(): List<AppInfo> = apps
+
+    override fun launch(packageName: String): Boolean = apps.any { it.packageName == packageName }
+}
+
+// 测试用 AppInfo 构造辅助函数
+// Test helper to construct an AppInfo
+fun FakeApp(packageName: String, label: String): AppInfo = AppInfo(packageName, label, null)
@@ -0,0 +1,14 @@
+package top.yeij.hearth.webview
+
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class JsBridgeTest {
+    @Test
+    fun getDeviceInfo_returnsJsonWithDarkMode() {
+        val bridge = JsBridge(deviceWidthPx = 800, deviceHeightPx = 480, density = 2.0f, darkMode = true)
+        val json = bridge.getDeviceInfo()
+        assertTrue(json.contains("\"widthPx\":800"))
+        assertTrue(json.contains("\"darkMode\":true"))
+    }
+}
@@ -0,0 +1,4 @@
+plugins {
+    id("com.android.application") version "8.6.1" apply false
+    id("org.jetbrains.kotlin.android") version "1.9.24" apply false
+}
@@ -0,0 +1,323 @@
+# Hearth 启动器 · 设计文档
+
+> 版本：v1.0
+> 日期：2026-08-16
+> 包名：`top.yeij.hearth`
+
+## 1. 概述
+
+Hearth 是一个面向瑞芯微 RK3566 横屏开发板（立创·泰山派）的 Android 启动器（Home）。
+核心特色：**界面全 H5 渲染，原生只当「能力层」**，通过 JS Bridge 向 H5 暴露系统能力，
+使得桌面 UI、卡片、webAPP 均可远程下发、动态扩展，无需重装 APK。
+
+### 目标平台
+
+| 项 | 值 |
+|---|---|
+| 硬件 | 立创·泰山派 RK3566 开发板 |
+| 系统 | Android 11（API 30） |
+| 屏幕 | 横屏 800×480 物理像素，高 DPI（≈300+，自适应系统 density） |
+| 兼容策略 | `minSdk = 30`，仅针对该板，不做低版本兼容 |
+
+## 2. 需求汇总（已确认）
+
+1. **全 H5 渲染架构**：桌面 = 全屏 WebView 承载 H5，原生只提供系统能力（查应用/启动应用/媒体状态/下载缓存等）。
+2. **全局左侧边栏**：Miuix NavigationRail 形态，可切换（收起 80px 纯图标 / 展开 240px 图标+文字），
+   用于切换 5 个页面：首页 / 沉浸首页 / H5 应用列表 / 安卓 APP 列表 / 设置。
+3. **首页**：左中右三栏卡片流。大字时间卡始终保留；媒体卡动态（有活动媒体才显示）；
+   日历/天气/小工具填充富余空间。**首页无应用入口（不做 Dock），应用只从列表页打开**。
+4. **卡片插件化**：每个卡片 = 独立 HTML + 一份 manifest（声明所需数据源/权限），可后期扩展、可远程下发。
+5. **沉浸首页（二期）**：左 2/3 freeform 窗口跑第三方 App + 右侧卡片列（时间/媒体/天气）。
+6. **列表页**：安卓 APP 列表 = 图标网格 + 搜索；H5 应用列表 = webAPP 富卡片（缩略图 + 在线/离线标签）。
+7. **webAPP 下发**：JSON 清单 + 可选离线包，远程下发 + 本地缓存。
+8. **UI 风格**：Miuix / HyperOS 视觉（纯视觉，H5 用 CSS 还原，非 Compose 库）。
+9. **状态栏**：系统默认沉浸式（全屏隐藏，顶部下滑一次展开，几秒自动收起）。
+10. **夜间模式**：跟随系统（`prefers-color-scheme`）。
+11. **横屏锁定**：固定横屏。
+
+## 3. 架构
+
+```
+┌──────────────────────── Hearth APK ────────────────────────┐
+│  MainActivity（唯一 Activity）                              │
+│    ├─ 窗口管理：全屏沉浸式 / 横屏锁定 / 夜间模式             │
+│    └─ WebView（全屏，加载 assets/index.html）                │
+│           │  window.HearthBridge (JS Bridge)                 │
+│           ▼                                                 │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │ 能力层（原生 Kotlin）                                 │    │
+│  │  ├─ AppRepository      查应用列表/图标/启动          │    │
+│  │  ├─ WebAppRepository   拉 webAPP 清单/离线包         │    │
+│  │  ├─ WebAppContainer    多 WebView 管理（标签/导航）   │    │
+│  │  ├─ CardRepository     卡片清单拉取/缓存             │    │
+│  │  ├─ MediaSessionSource 媒体状态监听                   │    │
+│  │  ├─ CacheManager       文件缓存（清单/离线包/图标）   │    │
+│  │  └─ JsBridge           暴露给 H5 的方法               │    │
+│  └────────────────────────────────────────────────────┘    │
+└────────────────────────────────────────────────────────────┘
+         │ 网络（webAPP / 卡片 服务器）
+         ▼
+   ┌─ 服务器 ──────────────┐
+   │  manifest.json        │ ← webAPP 清单
+   │  offlines/*.zip       │ ← 可选离线包
+   │  cards/catalog.json   │ ← 卡片目录
+   │  cards/<id>/card.html │ ← 卡片资源
+   └───────────────────────┘
+```
+
+### 模块职责（单一职责）
+
+| 模块 | 职责 | 依赖 |
+|---|---|---|
+| `MainActivity` | 窗口、生命周期、横屏锁、沉浸式 | WebViewManager |
+| `WebViewManager` | WebView 配置（内核设置、viewport、注册 JS Bridge） | JsBridge |
+| `JsBridge` | 所有 `@JavascriptInterface` 方法，H5 唯一入口 | 各 Repository/Source |
+| `AppRepository` | PackageManager 封装：应用列表、base64 图标、启动应用 | 无 |
+| `WebAppRepository` | 拉取 webAPP 清单、下载离线包、解析 | CacheManager |
+| `WebAppContainer` | 多 WebView 管理：标签页打开/切换/关闭、前进后退、重载 | 无 |
+| `CardRepository` | 拉取卡片目录、下载卡片资源 | CacheManager |
+| `MediaSessionSource` | 监听活跃媒体会话，推送媒体元数据 | 无 |
+| `CacheManager` | 文件读写缓存（清单/离线包/卡片/图标） | 无 |
+
+### 数据流（核心路径）
+
+1. **启动**：MainActivity 全屏 → WebView 加载 `assets/index.html`（H5 桌面，随 APK 打包，保证离线可用）。
+2. **渲染 APP 列表**：H5 调 `listApps()` → 原生查 PackageManager → 回调 JSON（含 base64 图标）→ H5 渲染网格。
+3. **渲染 webAPP 列表**：H5 调 `fetchWebApps()` → 原生拉服务器清单 → 缓存 → 回调 → H5 渲染富卡片。
+4. **启动 APP**：点击 → H5 调 `launchApp(pkg)` → 原生 `startActivity`。
+5. **打开 webAPP**：点击 → H5 调 `openWebApp(id)` → 原生新建内容 WebView（标签页）加载 URL，桌面 H5 顶部渲染浏览器式顶栏；回退/前进/重载/标签切换均经 JS Bridge 控制。
+6. **首页卡片**：H5 调 `fetchCards()` → 原生拉卡片目录 → 下载卡片 HTML + 数据 → H5 渲染三栏卡片流。
+7. **媒体卡**：原生 MediaSessionSource 监听媒体变化 → 事件推给 H5 → H5 显示/隐藏媒体卡。
+
+## 4. JS Bridge 协议
+
+H5 通过 `window.HearthBridge` 访问原生能力。所有方法异步回调（`callbackId` 模式或 Promise 封装）。
+
+### 4.1 H5 → 原生（方法调用）
+
+| 方法 | 参数 | 返回 | 说明 |
+|---|---|---|---|
+| `listApps()` | 无 | AppInfo[] | 已装应用列表（包名/名称/base64 图标） |
+| `launchApp(pkg)` | 包名 | void | 启动第三方应用 |
+| `fetchWebApps()` | 无 | WebApp[] | 拉取/返回 webAPP 清单（含缓存逻辑） |
+| `openWebApp(id)` | webAPP id | void | 打开 webAPP（新建内容 WebView 标签页 + 显示顶栏） |
+| `closeWebApp(id)` | webAPP id | void | 关闭指定标签页 |
+| `switchTab(id)` | 标签 id | void | 切换可见标签页 |
+| `listTabs()` | 无 | Tab[] | 返回已打开标签列表 |
+| `webGoBack()` | 无 | void | 当前标签回退 |
+| `webGoForward()` | 无 | void | 当前标签前进 |
+| `webReload()` | 无 | void | 当前标签重载 |
+| `backToHome()` | 无 | void | 关闭全部标签，回到桌面 |
+| `fetchCards()` | 无 | Card[] | 拉取/返回卡片目录 |
+| `getDeviceInfo()` | 无 | DeviceInfo | 分辨率、density、深色模式等 |
+| `launchInBounds(pkg, x,y,w,h)` | 二期 | void | freeform 启动到指定区域 |
+
+### 4.2 原生 → H5（事件推送）
+
+原生通过 `HearthEvents`（JS 注入回调）推送事件：
+
+| 事件 | 载荷 | 触发时机 |
+|---|---|---|
+| `media-session-changed` | MediaInfo | 媒体播放状态/歌曲变化 |
+| `theme-changed` | `"light"\|"dark"` | 系统夜间模式切换 |
+| `webapp-updated` | WebApp[] | webAPP 清单更新 |
+
+### 4.3 数据结构
+
+```jsonc
+// AppInfo
+{ "packageName": "com.x.y", "label": "音乐", "icon": "data:image/png;base64,..." }
+
+// WebApp
+{
+  "id": "cloud-music", "name": "云音乐",
+  "icon": "https://host/icon.svg", "url": "https://host/app/index.html",
+  "offline": { "package": "offline/cloud-music.zip", "version": "1.0.0" }
+}
+
+// MediaInfo
+{ "title": "海阔天空", "artist": "Beyond", "album": "乐与怒",
+  "cover": "data:image/png;base64,...", "position": 120000, "duration": 245000,
+  "playing": true, "packageName": "com.x.player" }
+
+// DeviceInfo
+{ "widthPx": 800, "heightPx": 480, "density": 2.0, "darkMode": true }
+```
+
+## 5. 卡片插件系统
+
+### 5.1 卡片包结构
+
+```
+cards/<card-id>/
+├── card.html        # 卡片 UI（独立 HTML 片段）
+├── manifest.json    # 声明数据源/权限
+└── assets/          # 卡片私有资源（可选）
+```
+
+### 5.2 manifest 格式
+
+```jsonc
+{
+  "id": "media-card",
+  "name": "媒体卡片",
+  "version": "1.0.0",
+  "entry": "card.html",
+  "dataSources": ["time", "media-session"],   // 需要的数据源
+  "permissions": ["MEDIA_CONTENT_CONTROL"],     // 对应的系统权限
+  "priority": 1,                                // 优先级（数字小者优先占位）
+  "size": { "min": "1x1", "max": "2x2" }        // 尺寸偏好
+}
+```
+
+### 5.3 数据源类型
+
+原生能力层提供的「数据源」，卡片通过 manifest 声明所需：
+
+| 数据源 | 说明 | 权限 |
+|---|---|---|
+| `time` | 时间/日期 | 无 |
+| `media-session` | 媒体状态 | `MEDIA_CONTENT_CONTROL` + 通知监听授权 |
+| `weather` | 天气 | 网络 + 城市配置 |
+| `calendar` | 日历 | `READ_CALENDAR` |
+| `system` | 系统信息（内存/存储） | 无/部分 |
+
+### 5.4 卡片加载与降级
+
+1. H5 获取卡片目录 → 下载卡片资源到本地缓存。
+2. 按 `priority` 排序，三栏容器依次放置。
+3. 卡片数据源未授权/无数据时，该卡片不渲染，由低优先级卡片（日历/天气）填充。
+4. 大字时间卡为**内置卡片**，始终保留，不参与降级。
+
+## 6. webAPP 下发协议
+
+### 6.1 清单格式（manifest.json）
+
+```jsonc
+{
+  "version": 1,
+  "updatedAt": 1723785600,
+  "apps": [
+    {
+      "id": "cloud-music", "name": "云音乐",
+      "icon": "https://host/icon.svg", "url": "https://host/app/index.html",
+      "offline": { "package": "offline/cloud-music.zip", "version": "1.0.0", "size": 1048576 }
+    }
+  ]
+}
+```
+
+### 6.2 下发与缓存策略
+
+1. 启动/定时拉取清单 → 对比本地 `version`。
+2. 有新版本 → 下载清单 + 各 webAPP 图标/离线包。
+3. 本地缓存失败降级：**有旧清单用旧清单，无清单显示空态 + 错误提示**。
+4. webAPP 打开时：有离线包且离线 → 加载本地解压目录；否则加载远程 URL。
+
+### 6.3 webAPP 打开行为（浏览器式顶栏 + 多标签）
+
+- 打开 webAPP → 原生新建内容 WebView（标签页）加载，桌面 H5 顶部渲染浏览器式顶栏。
+- 顶栏：回退 / 前进 / 重载（作用于当前标签）；右侧标签页入口，可切换 / 关闭已打开标签。
+- 每个标签页 = 一个独立 WebView，拥有独立前进后退历史。
+- 关闭全部标签 = 回到桌面。
+
+## 7. UI 设计
+
+### 7.1 视觉规范（Miuix / HyperOS 风格，CSS 还原）
+
+- **配色**：双色 token（CSS 变量），浅色/深色两套。
+- **壁纸透明**：`html`/`body` 背景透明以透出壁纸。
+- **卡片玻璃拟态（HyperOS 4 柔光玻璃）**：卡片、侧边栏、列表容器等 UI 元素用半透明背景 + `backdrop-filter: blur(20px) saturate(1.2) brightness(1.05) contrast(1.1)`（柔光玻璃 = 高斯模糊 + 饱和度/亮度/对比度微调，参数参考 Miuix `miuix-blur`）；深色 `rgba(21,21,24,0.55)`、浅色 `rgba(255,255,255,0.4)` 半透明混合层；配 1px 半透明描边；旧 WebView 不支持 `backdrop-filter` 时降级为纯半透明背景。
+- **圆角**：squircle 平滑圆角（卡片 14px 左右）。
+- **字体**：MiSans（远程字体或系统默认）。
+- **强调色**：小米橙 `#ff6900`（选中态/进度条）。
+- **侧边栏选中态**：橙色高亮药丸。
+
+### 7.2 页面布局
+
+| 页面 | 布局 |
+|---|---|
+| 首页 | 三栏卡片流：大字时间（始终）+ 媒体卡（动态）+ 日历/天气/小工具（填充） |
+| 沉浸首页（二期） | 左 2/3 freeform 窗口 + 右卡片列（时间/媒体/天气） |
+| 安卓 APP 列表 | 顶部搜索框 + 图标网格（图标+名称） |
+| H5 应用列表 | 顶部搜索框 + webAPP 富卡片（缩略图 + 在线/离线标签） |
+| 设置 | Miuix Preference 分组：显示 / 网络 / 关于 |
+
+### 7.3 侧边栏
+
+- 收起：80px，纯图标（无文字）。
+- 展开：240px，图标 + 文字横排，选中项后橙色高亮药丸。
+- 左上角按钮切换收起/展开。
+- **非首页时**：侧边栏最顶部（Header 区域）显示一个小时间；首页时不显示。
+
+### 7.4 夜间模式
+
+- H5 用 CSS 变量 + `prefers-color-scheme` 跟随系统。
+- 原生保证 WebView 跟随 `Configuration.uiMode`，无需额外处理。
+
+### 7.5 webAPP 顶栏
+
+- 左侧：回退、前进、重载三个图标按钮。
+- 右侧：标签页入口按钮（点击展开标签列表，可切换 / 关闭）。
+- 顶栏随 webAPP 打开而显示，关闭全部标签后隐藏。
+
+## 8. 窗口管理
+
+- **全屏沉浸式**：`WindowInsetsController.hide(statusBars() | navigationBars())`，行为 `BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE`（系统默认：下滑一次展开、几秒自动收起）。
+- **横屏锁定**：`screenOrientation = landscape`。
+- **默认桌面**：Manifest 声明 `HOME` + `DEFAULT` intent-filter，用户手动设为默认。
+- **Back 键屏蔽**：桌面状态下拦截 Back 键（按返回无响应）；webAPP 打开时 Back 先作用于标签页回退，无历史可回退则关闭标签。
+- **壁纸显示**：Activity 窗口开启壁纸（theme `showWallpaper` / `WallpaperManager`），WebView `setBackgroundColor(TRANSPARENT)`，配合 H5 页面透明透出壁纸。
+
+## 9. 权限模型
+
+| 权限 | 用途 | 授予方式 |
+|---|---|---|
+| `QUERY_ALL_PACKAGES` | 查询已装应用列表 | launcher 豁免，声明即生效 |
+| `MEDIA_CONTENT_CONTROL` | 读取媒体状态 | 运行时 + 通知监听授权（用户手动） |
+| `READ_CALENDAR` | 日历卡片数据 | 运行时授权 |
+| `INTERNET` | 拉取 webAPP/卡片 | 声明即生效 |
+
+## 10. 错误处理
+
+| 场景 | 处理 |
+|---|---|
+| webAPP 清单拉取失败 | 用本地缓存清单；无缓存则空态 + 提示 |
+| 离线包下载失败 | 标记「在线」，下次拉取重试 |
+| 媒体权限未授权 | 媒体卡不渲染，降级日历/天气 |
+| WebView 加载失败 | 错误页 + 重试按钮 |
+| 系统 WebView 缺失 | 启动检测，提示（或引导安装） |
+| 第三方 App 无法 freeform（二期） | 捕获异常，提示该 App 不支持小窗 |
+
+## 11. 测试策略
+
+- **TDD**：先写测试再写实现。
+- **原生单测**：Repository 层（mock PackageManager / 网络 / CacheManager）。
+- **JS Bridge 协议测试**：mock H5 调用，验证方法签名与返回结构。
+- **H5 侧**：卡片/页面为纯静态，用轻量 JS 单测覆盖数据拼接与降级逻辑。
+- **真机集成**：adb 安装到板子，验证 HOME、沉浸式、媒体权限、webAPP 拉取。
+
+## 12. 技术栈与依赖
+
+| 项 | 选择 |
+|---|---|
+| 语言 | Kotlin |
+| SDK | minSdk 30 / targetSdk 30 |
+| WebView | 系统内核（需上板验证存在） |
+| 网络 | OkHttp |
+| JSON | Gson |
+| H5 | 纯 HTML/CSS/JS，无框架（SPA 手写） |
+| 构建 | Gradle（Android Gradle Plugin） |
+
+## 13. 二期规划（不在本期实现）
+
+1. **freeform 小窗**（沉浸首页）：`FreeformWindowManager` 模块 + `launchInBounds` 能力。
+   - 前提：固件开启 `enable_freeform_support`，需上板验证。
+2. 更多首页候选卡片（随卡片插件系统扩展）。
+
+## 14. 明确不做（YAGNI）
+
+- 完整 kiosk 锁定（Home / 最近任务 / 系统手势全锁，仅 Back 键已做）
+- 屏幕常亮管理
+- 多用户 / Widget 宿主
+- 应用图标拖拽 / 文件夹 / Dock
@@ -0,0 +1,6 @@
+org.gradle.jvmargs=-Xmx2048m
+android.useAndroidX=true
+android.aapt2FromMavenOverride=/home/Aska/Android/Sdk/build-tools/34.0.0/aapt2
+# 禁用 AGP 自动下载 SDK 组件（本机无法访问 dl.google.com，避免配置阶段卡死）
+# Disable AGP auto-download of SDK components (dl.google.com unreachable, avoid hang during config)
+android.builder.sdkDownload=false
@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
@@ -0,0 +1,252 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"
@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega
@@ -0,0 +1,18 @@
+pluginManagement {
+    repositories {
+        maven("https://maven.aliyun.com/repository/google")
+        maven("https://maven.aliyun.com/repository/central")
+        maven("https://maven.aliyun.com/repository/gradle-plugin")
+        google(); mavenCentral(); gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        maven("https://maven.aliyun.com/repository/google")
+        maven("https://maven.aliyun.com/repository/central")
+        google(); mavenCentral()
+    }
+}
+rootProject.name = "Hearth"
+include(":app")
Author	SHA1	Message	Date
AskaEth	dcb712731d	fix: single-query listApps	2026-08-16 16:12:44 +08:00
AskaEth	77b52223c6	docs: add wallpaper transparency and hyperos-4 soft-glass style	2026-08-16 16:09:21 +08:00
AskaEth	c4c19b610c	feat: app repository for list and launch apps	2026-08-16 16:08:37 +08:00
AskaEth	df0f9a2615	chore: disable AGP SDK auto-download (dl.google.com unreachable)	2026-08-16 16:01:36 +08:00
AskaEth	394a553da7	feat: webview manager and js bridge skeleton	2026-08-16 16:01:36 +08:00
AskaEth	a764208c0e	feat: android project skeleton with immersive home activity	2026-08-16 15:34:45 +08:00
AskaEth	bb3699267f	docs: adapt plan for arm64 build environment	2026-08-16 15:19:07 +08:00
AskaEth	4d1c4b294b	docs: add implementation plan	2026-08-16 15:01:29 +08:00
AskaEth	425ffc42c9	docs: add webapp tab bar, back-key suppression, sidebar clock	2026-08-16 14:57:57 +08:00
AskaEth	5b5dc20f5a	docs: add launcher design spec	2026-08-16 14:45:49 +08:00