android-sdd 1.0.0

package/skills/System Integration/App Widget/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: app-widget
+description: >
+  Home screen App Widget implementation in Android.
+  Load this skill when building home screen widgets, updating widget
+  content, handling widget interactions, using Glance for Compose-based
+  widgets, or configuring widget metadata.
+---
+
+# App Widget
+
+## Overview
+App Widgets are miniature app views displayed on the home screen or lock screen. They update periodically and respond to user interactions. Modern widgets are best built with **Glance** (Jetpack Compose-based API). Legacy widgets use `RemoteViews`.
+
+---
+
+## Core Principles
+
+- Use **Glance** for new widgets — it provides a Compose-like API over RemoteViews
+- Widgets run in a separate process — keep updates lightweight and fast
+- Update widgets via `AppWidgetManager` — not direct state mutation
+- Provide a `configure` activity if the widget needs user setup
+- Minimize update frequency — excessive updates drain battery
+
+---
+
+## Glance Widget (Recommended)
+
+```kotlin
+// ✅ Glance widget — Compose-like API
+class StatsWidget : GlanceAppWidget() {
+
+    override suspend fun provideGlance(context: Context, id: GlanceId) {
+        // Load data before composing
+        val stats = statsRepository.getStats()
+
+        provideContent {
+            StatsWidgetContent(stats)
+        }
+    }
+}
+
+@Composable
+fun StatsWidgetContent(stats: Stats) {
+    Column(
+        modifier = GlanceModifier
+            .fillMaxSize()
+            .background(GlanceTheme.colors.widgetBackground)
+            .padding(16.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(
+            text = stats.title,
+            style = TextStyle(
+                color = GlanceTheme.colors.onSurface,
+                fontSize = 16.sp,
+                fontWeight = FontWeight.Bold
+            )
+        )
+        Spacer(modifier = GlanceModifier.height(8.dp))
+        Text(
+            text = stats.value,
+            style = TextStyle(
+                color = GlanceTheme.colors.primary,
+                fontSize = 32.sp
+            )
+        )
+        Button(
+            text = "Refresh",
+            onClick = actionRunCallback<RefreshAction>()
+        )
+    }
+}
+```
+
+---
+
+## Glance Action
+
+```kotlin
+// ✅ Handle widget button tap
+class RefreshAction : ActionCallback {
+    override suspend fun onAction(
+        context: Context,
+        glanceId: GlanceId,
+        parameters: ActionParameters
+    ) {
+        // Trigger data refresh then update widget
+        statsRepository.refresh()
+        StatsWidget().update(context, glanceId)
+    }
+}
+```
+
+---
+
+## Glance Widget Receiver
+
+```kotlin
+// ✅ AppWidgetReceiver for Glance widgets
+class StatsWidgetReceiver : GlanceAppWidgetReceiver() {
+    override val glanceAppWidget: GlanceAppWidget = StatsWidget()
+}
+```
+
+---
+
+## Widget Metadata (XML)
+
+```xml
+<!-- res/xml/stats_widget_info.xml -->
+<appwidget-provider
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:minWidth="180dp"
+    android:minHeight="110dp"
+    android:targetCellWidth="2"
+    android:targetCellHeight="2"
+    android:updatePeriodMillis="1800000"
+    android:initialLayout="@layout/widget_loading"
+    android:description="@string/widget_description"
+    android:previewImage="@drawable/widget_preview"
+    android:widgetCategory="home_screen" />
+```
+
+---
+
+## Manifest Registration
+
+```xml
+<receiver
+    android:name=".widget.StatsWidgetReceiver"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+    </intent-filter>
+    <meta-data
+        android:name="android.appwidget.provider"
+        android:resource="@xml/stats_widget_info" />
+</receiver>
+```
+
+---
+
+## Updating Widget from App
+
+```kotlin
+// ✅ Update all instances of a widget
+suspend fun updateAllWidgets(context: Context) {
+    val manager = GlanceAppWidgetManager(context)
+    val glanceIds = manager.getGlanceIds(StatsWidget::class.java)
+    glanceIds.forEach { glanceId ->
+        StatsWidget().update(context, glanceId)
+    }
+}
+
+// ✅ Trigger update from WorkManager for periodic refresh
+class WidgetUpdateWorker(context: Context, params: WorkerParameters) :
+    CoroutineWorker(context, params) {
+    override suspend fun doWork(): Result {
+        updateAllWidgets(applicationContext)
+        return Result.success()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Doing heavy work directly in `provideGlance` on the main thread — use `withContext(Dispatchers.IO)`
+- Setting `updatePeriodMillis` too low — minimum enforced is 30 minutes
+- Using `RemoteViews` for new widgets when Glance is available — harder to maintain
+- Not providing a preview image — widget looks broken in the picker
+- Keeping large bitmaps in widget state — causes TransactionTooLargeException
+
+---
+
+## Related Skills
+- `glance` — detailed Glance API patterns
+- `workmanager` — scheduling periodic widget updates
+- `notification` — alternative for time-sensitive updates
+- `compose` — Compose fundamentals that inform Glance's API

package/skills/System Integration/Deep Link/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: deep-link
+description: >
+  Deep link handling at the Android system level.
+  Load this skill when configuring intent filters, handling incoming URIs
+  in the Activity, setting up App Links with digital asset links,
+  or processing deep links from notifications and external apps.
+---
+
+# Deep Link
+
+## Overview
+Deep links allow external sources — browsers, other apps, notifications — to open a specific screen inside your app via a URI. Android supports two types: custom scheme deep links (`myapp://`) and App Links (`https://`). App Links require domain verification and are more secure.
+
+---
+
+## Core Principles
+
+- Prefer **App Links** (HTTPS) over custom schemes — they can't be intercepted by other apps
+- Verify App Links with `assetlinks.json` hosted on your domain
+- Parse the URI in the Activity and delegate to the navigation system — don't handle in the manifest
+- Validate all incoming URI parameters — treat them as untrusted input
+- Test deep links with `adb` before release
+
+---
+
+## Manifest Intent Filters
+
+```xml
+<!-- AndroidManifest.xml -->
+<activity
+    android:name=".MainActivity"
+    android:exported="true"
+    android:launchMode="singleTask">
+
+    <!-- App Link (HTTPS — requires domain verification) -->
+    <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"
+            android:host="example.com"
+            android:pathPrefix="/users" />
+    </intent-filter>
+
+    <!-- Custom scheme (no verification required) -->
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="myapp" />
+    </intent-filter>
+
+</activity>
+```
+
+---
+
+## App Links Verification (assetlinks.json)
+
+```json
+// Hosted at: https://example.com/.well-known/assetlinks.json
+[{
+  "relation": ["delegate_permission/common.handle_all_urls"],
+  "target": {
+    "namespace": "android_app",
+    "package_name": "com.example.app",
+    "sha256_cert_fingerprints": [
+      "AA:BB:CC:DD:..."
+    ]
+  }
+}]
+```
+
+```bash
+# Get your app's SHA-256 fingerprint
+keytool -list -v -keystore release.keystore -alias my_alias
+```
+
+---
+
+## Handling the Deep Link in Activity
+
+```kotlin
+// ✅ Navigation Compose handles deep links automatically
+// Just ensure your NavHost is set up with deep links on destinations (see deep-navigation skill)
+
+// ✅ Manual handling if needed
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        handleDeepLinkIntent(intent)
+        setContent { AppNavHost() }
+    }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        handleDeepLinkIntent(intent)
+    }
+
+    private fun handleDeepLinkIntent(intent: Intent?) {
+        val uri = intent?.data ?: return
+        // Navigation Compose picks this up automatically via NavHost
+        // Manual parsing only needed outside of Navigation Compose
+    }
+}
+```
+
+---
+
+## URI Validation
+
+```kotlin
+// ✅ Validate and sanitize deep link parameters
+fun parseUserDeepLink(uri: Uri): String? {
+    if (uri.host != "example.com") return null
+    if (!uri.path.orEmpty().startsWith("/users/")) return null
+
+    val userId = uri.lastPathSegment ?: return null
+    if (userId.isBlank() || userId.length > 64) return null
+    if (!userId.matches(Regex("[a-zA-Z0-9_-]+"))) return null
+
+    return userId
+}
+```
+
+---
+
+## Testing Deep Links
+
+```bash
+# Test App Link
+adb shell am start \
+  -W -a android.intent.action.VIEW \
+  -d "https://example.com/users/123" \
+  com.example.app
+
+# Test custom scheme
+adb shell am start \
+  -W -a android.intent.action.VIEW \
+  -d "myapp://users/123" \
+  com.example.app
+
+# Verify App Link association
+adb shell pm get-app-links com.example.app
+```
+
+---
+
+## Deep Link from Notification
+
+```kotlin
+// ✅ Build notification with deep link PendingIntent
+fun buildDeepLinkPendingIntent(context: Context, userId: String): PendingIntent {
+    val deepLinkUri = Uri.parse("https://example.com/users/$userId")
+    val intent = Intent(Intent.ACTION_VIEW, deepLinkUri).apply {
+        setPackage(context.packageName)
+        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    }
+    return TaskStackBuilder.create(context).run {
+        addNextIntentWithParentStack(intent)
+        getPendingIntent(
+            userId.hashCode(),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )!!
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using only custom scheme deep links for sensitive actions — other apps can register the same scheme
+- Not verifying App Links — browser asks user to choose the app instead of opening directly
+- Not validating URI parameters — path traversal or injection via malicious links
+- Not handling `onNewIntent` — deep links sent to an already-running activity are ignored
+- Trusting all incoming URIs without validation — treat as untrusted user input
+
+---
+
+## Related Skills
+- `deep-navigation` — wiring deep links into Navigation Compose destinations
+- `notification` — launching deep links from notifications
+- `manifest` — intent filter configuration
+- `nested-navigation` — deep linking into nested navigation graphs

package/skills/System Integration/Foreground Service/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: foreground-service
+description: >
+  Foreground Service implementation in Android.
+  Load this skill when running long-running user-visible operations like
+  media playback, file upload/download, location tracking, or any task
+  that must run while the app is in background with a visible notification.
+---
+
+# Foreground Service
+
+## Overview
+A Foreground Service runs in the background while showing a persistent notification. It survives app backgrounding and is used for operations the user is actively aware of — music playback, navigation, ongoing uploads. Since Android 14, foreground service types must be declared explicitly.
+
+---
+
+## Core Principles
+
+- Always show a **meaningful notification** — it's required and user-facing
+- Declare the correct **foreground service type** in the manifest
+- Stop the service when the work is done — `stopSelf()` or `stopForeground()`
+- Use `CoroutineScope` inside the service for async work
+- Prefer WorkManager for deferrable work — ForegroundService is for user-visible ongoing tasks
+
+---
+
+## Manifest Declaration
+
+```xml
+<!-- AndroidManifest.xml -->
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+<!-- Add the type matching your use case -->
+
+<application>
+    <service
+        android:name=".service.UploadService"
+        android:foregroundServiceType="dataSync"
+        android:exported="false" />
+</application>
+```
+
+---
+
+## Service Types Reference
+
+| Type | Use Case |
+|------|----------|
+| `dataSync` | Upload / download / sync |
+| `mediaPlayback` | Music / podcast playback |
+| `location` | Navigation, location tracking |
+| `camera` | Video recording |
+| `microphone` | Audio recording |
+| `connectedDevice` | Bluetooth device communication |
+
+---
+
+## Basic Foreground Service
+
+```kotlin
+// ✅ Foreground service with coroutine scope
+class UploadService : Service() {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private var uploadJob: Job? = null
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_START -> {
+                val fileUri = intent.getStringExtra(EXTRA_FILE_URI) ?: run {
+                    stopSelf()
+                    return START_NOT_STICKY
+                }
+                startForegroundWithNotification()
+                startUpload(fileUri)
+            }
+            ACTION_CANCEL -> cancelUpload()
+        }
+        return START_NOT_STICKY
+    }
+
+    private fun startForegroundWithNotification() {
+        val notification = buildNotification("Starting upload…")
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            startForeground(NOTIFICATION_ID, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC)
+        } else {
+            startForeground(NOTIFICATION_ID, notification)
+        }
+    }
+
+    private fun startUpload(fileUri: String) {
+        uploadJob = scope.launch {
+            try {
+                uploadRepository.upload(Uri.parse(fileUri)) { progress ->
+                    updateNotification("Uploading… $progress%")
+                }
+                updateNotification("Upload complete")
+                delay(2_000)
+            } catch (e: CancellationException) {
+                updateNotification("Upload cancelled")
+            } catch (e: Exception) {
+                updateNotification("Upload failed: ${e.message}")
+            } finally {
+                stopForeground(STOP_FOREGROUND_REMOVE)
+                stopSelf()
+            }
+        }
+    }
+
+    private fun cancelUpload() {
+        uploadJob?.cancel()
+    }
+
+    override fun onDestroy() {
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    private fun buildNotification(text: String): Notification {
+        createNotificationChannel()
+        return NotificationCompat.Builder(this, CHANNEL_ID)
+            .setContentTitle("File Upload")
+            .setContentText(text)
+            .setSmallIcon(R.drawable.ic_upload)
+            .setOngoing(true)
+            .build()
+    }
+
+    private fun updateNotification(text: String) {
+        val manager = getSystemService(NotificationManager::class.java)
+        manager.notify(NOTIFICATION_ID, buildNotification(text))
+    }
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID, "Upload", NotificationManager.IMPORTANCE_LOW
+            )
+            getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
+        }
+    }
+
+    companion object {
+        const val ACTION_START = "action_start"
+        const val ACTION_CANCEL = "action_cancel"
+        const val EXTRA_FILE_URI = "file_uri"
+        private const val NOTIFICATION_ID = 1001
+        private const val CHANNEL_ID = "upload_channel"
+
+        fun startIntent(context: Context, fileUri: Uri): Intent =
+            Intent(context, UploadService::class.java).apply {
+                action = ACTION_START
+                putExtra(EXTRA_FILE_URI, fileUri.toString())
+            }
+
+        fun cancelIntent(context: Context): Intent =
+            Intent(context, UploadService::class.java).apply {
+                action = ACTION_CANCEL
+            }
+    }
+}
+```
+
+---
+
+## Starting the Service
+
+```kotlin
+// ✅ Start from ViewModel via event
+class UploadViewModel : ViewModel() {
+    private val _events = Channel<UploadEvent>(Channel.BUFFERED)
+    val events = _events.receiveAsFlow()
+
+    fun onUploadClick(fileUri: Uri) {
+        viewModelScope.launch {
+            _events.send(UploadEvent.StartService(fileUri))
+        }
+    }
+}
+
+// ✅ Handle in composable / activity
+LaunchedEffect(Unit) {
+    viewModel.events.collect { event ->
+        when (event) {
+            is UploadEvent.StartService -> {
+                val intent = UploadService.startIntent(context, event.fileUri)
+                context.startForegroundService(intent)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Starting a ForegroundService for short tasks — use coroutines or WorkManager
+- Not calling `stopSelf()` when work completes — service stays alive indefinitely
+- Missing `foregroundServiceType` in manifest on Android 10+ — SecurityException
+- Doing heavy work on the main thread inside `onStartCommand` — use a coroutine scope
+- Not cancelling the coroutine scope in `onDestroy` — coroutine leak
+
+---
+
+## Related Skills
+- `workmanager` — deferrable background work without a notification requirement
+- `notification` — building and updating notifications
+- `background-processing` — choosing the right background mechanism
+- `coroutine` — coroutine scope inside services