feat(clipboard): expose macOS 15.4+ access-behavior getter

- Clipboard.accessBehavior: AccessBehavior? reads NSPasteboard.accessBehavior,
  null when the host OS has no privacy model.
- Clipboard.isAccessBehaviorSupported gates UI based on respondsToSelector:
  probing for both getter and setter.
- Native nativeGetAccessBehavior + nativeIsAccessBehaviorSupported in the JNI
  bridge; both guarded via NSInvocation + respondsToSelector.
- Example Clipboard tab: new "Privacy — macOS 15.4+" card showing the current
  policy with chips for the three values; disabled chips + explanatory copy on
  older macOS / other OSes.
- Docs updated (runtime/clipboard-common.md, runtime/clipboard-macos.md).

Author: kdroidFilter

clipboard-common/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/Clipboard.kt

@@ -119,6 +119,15 @@ object Clipboard {
     /** Sets the platform privacy policy for background reads. No-op outside macOS 15.4+. */
     fun setAccessBehavior(behavior: AccessBehavior) = backend.setAccessBehavior(behavior)
 
+    /**
+     * Currently effective privacy policy, or `null` when the host OS does not
+     * expose one (macOS < 15.4, Windows, Linux — treat as unrestricted).
+     */
+    val accessBehavior: AccessBehavior? get() = backend.accessBehavior()
+
+    /** True when [setAccessBehavior] and [accessBehavior] are honored (macOS 15.4+). */
+    val isAccessBehaviorSupported: Boolean get() = backend.isAccessBehaviorSupported()
+
     /**
      * Cold [Flow] that emits whenever the clipboard contents change.
      *

clipboard-common/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/internal/ClipboardBackend.kt

@@ -12,6 +12,7 @@ import java.nio.file.Path
  * [isAvailable] returns `false`). The facade in [io.github.kdroidfilter.nucleus.clipboard.Clipboard]
  * picks the first available backend and delegates.
  */
+@Suppress("TooManyFunctions")
 interface ClipboardBackend {
     /** Human-readable backend name, for logging. */
     val name: String
@@ -47,4 +48,15 @@ interface ClipboardBackend {
 
     /** Sets the platform privacy policy (macOS 15.4+). No-op elsewhere. */
     fun setAccessBehavior(behavior: AccessBehavior)
+
+    /**
+     * Reads the currently effective privacy policy.
+     *
+     * Returns `null` when the host OS has no such concept (macOS < 15.4,
+     * Windows, Linux) — callers should interpret this as "unrestricted access".
+     */
+    fun accessBehavior(): AccessBehavior?
+
+    /** True when [setAccessBehavior] and [accessBehavior] are honored by the backend. */
+    fun isAccessBehaviorSupported(): Boolean
 }

clipboard-common/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/internal/NoOpBackend.kt

@@ -4,6 +4,7 @@ import io.github.kdroidfilter.nucleus.clipboard.AccessBehavior
 import io.github.kdroidfilter.nucleus.clipboard.ClipboardFormat
 import java.nio.file.Path
 
+@Suppress("TooManyFunctions")
 internal object NoOpBackend : ClipboardBackend {
     override val name: String = "no-op"
 
@@ -28,4 +29,8 @@ internal object NoOpBackend : ClipboardBackend {
     override fun changeCount(): Long = 0L
 
     override fun setAccessBehavior(behavior: AccessBehavior) = Unit
+
+    override fun accessBehavior(): AccessBehavior? = null
+
+    override fun isAccessBehaviorSupported(): Boolean = false
 }

clipboard-macos/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/macos/MacClipboardBackend.kt

@@ -79,6 +79,15 @@ class MacClipboardBackend : ClipboardBackend {
         NativeMacClipboardBridge.nativeSetAccessBehavior(behavior.ordinal)
     }
 
+    override fun accessBehavior(): AccessBehavior? {
+        if (!NativeMacClipboardBridge.isLoaded) return null
+        val raw = NativeMacClipboardBridge.nativeGetAccessBehavior()
+        return AccessBehavior.entries.getOrNull(raw)
+    }
+
+    override fun isAccessBehaviorSupported(): Boolean =
+        NativeMacClipboardBridge.isLoaded && NativeMacClipboardBridge.nativeIsAccessBehaviorSupported()
+
     /**
      * Strips a leading UTF-8 BOM (`\uFEFF`) that Firefox and some web apps emit on
      * `public.html` payloads. Keeps the rest untouched.

clipboard-macos/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/macos/NativeMacClipboardBridge.kt

@@ -9,6 +9,7 @@ private const val LIBRARY_NAME = "nucleus_clipboard"
  * pasteboard and are safe to call from any thread (NSPasteboard is thread-safe,
  * and the ObjC side wraps each entry in an autorelease pool).
  */
+@Suppress("TooManyFunctions")
 internal object NativeMacClipboardBridge {
     private val loaded = NativeLibraryLoader.load(LIBRARY_NAME, NativeMacClipboardBridge::class.java)
 
@@ -62,4 +63,15 @@ internal object NativeMacClipboardBridge {
      */
     @JvmStatic
     external fun nativeSetAccessBehavior(value: Int)
+
+    /**
+     * Reads `NSPasteboard.accessBehavior`. Returns the raw enum value on
+     * macOS 15.4+, or `-1` when the property is not exposed by the runtime.
+     */
+    @JvmStatic
+    external fun nativeGetAccessBehavior(): Int
+
+    /** True when `NSPasteboard` responds to the `accessBehavior` selectors. */
+    @JvmStatic
+    external fun nativeIsAccessBehaviorSupported(): Boolean
 }

clipboard-macos/src/main/native/macos/nucleus_clipboard.m

@@ -323,3 +323,34 @@ static jobjectArray toJStringArray(JNIEnv *env, NSArray<NSString *> *items) {
         [inv invoke];
     }
 }
+
+JNIEXPORT jint JNICALL
+Java_io_github_kdroidfilter_nucleus_clipboard_macos_NativeMacClipboardBridge_nativeGetAccessBehavior(
+    JNIEnv *env, jclass cls) {
+    (void)env; (void)cls;
+    @autoreleasepool {
+        NSPasteboard *pb = [NSPasteboard generalPasteboard];
+        SEL sel = NSSelectorFromString(@"accessBehavior");
+        if (![pb respondsToSelector:sel]) return -1;
+        NSMethodSignature *sig = [pb methodSignatureForSelector:sel];
+        NSInvocation *inv = [NSInvocation invocationWithMethodSignature:sig];
+        [inv setSelector:sel];
+        [inv setTarget:pb];
+        [inv invoke];
+        NSInteger result = 0;
+        [inv getReturnValue:&result];
+        return (jint)result;
+    }
+}
+
+JNIEXPORT jboolean JNICALL
+Java_io_github_kdroidfilter_nucleus_clipboard_macos_NativeMacClipboardBridge_nativeIsAccessBehaviorSupported(
+    JNIEnv *env, jclass cls) {
+    (void)env; (void)cls;
+    @autoreleasepool {
+        NSPasteboard *pb = [NSPasteboard generalPasteboard];
+        BOOL hasGetter = [pb respondsToSelector:NSSelectorFromString(@"accessBehavior")];
+        BOOL hasSetter = [pb respondsToSelector:NSSelectorFromString(@"setAccessBehavior:")];
+        return (hasGetter && hasSetter) ? JNI_TRUE : JNI_FALSE;
+    }
+}

docs/runtime/clipboard-common.md

@@ -54,6 +54,8 @@ Singleton façade. All suspending methods may be called from any coroutine conte
 | `isAvailable: Boolean` | `true` when a platform backend is loaded and operational. `false` on unsupported platforms or when the native library failed to load. |
 | `backendName: String` | Backend name for diagnostics (e.g. `"macOS NSPasteboard"` or `"no-op"`). |
 | `setAccessBehavior(behavior)` | Applies a privacy policy for background reads. Maps to `NSPasteboard.accessBehavior` on macOS 15.4+, no-op elsewhere. |
+| `accessBehavior: AccessBehavior?` | Currently effective policy, or `null` when the host OS has no such concept (treat as unrestricted). |
+| `isAccessBehaviorSupported: Boolean` | `true` when the backend honors `setAccessBehavior` / `accessBehavior` (macOS 15.4+). |
 
 #### Read
 
@@ -157,7 +159,10 @@ enum class AccessBehavior { AlwaysAllow, AskEveryTime, AlwaysDeny }
 Platform privacy policy for background reads. Maps 1:1 to `NSPasteboard.AccessBehavior` on macOS 15.4+. No-op on platforms without a privacy model. Call at startup:
 
 ```kotlin
-Clipboard.setAccessBehavior(AccessBehavior.AskEveryTime)
+if (Clipboard.isAccessBehaviorSupported) {
+    Clipboard.setAccessBehavior(AccessBehavior.AskEveryTime)
+}
+val effective: AccessBehavior? = Clipboard.accessBehavior // null on macOS < 15.4
 ```
 
 ## Sensitive-content note

docs/runtime/clipboard-macos.md

@@ -54,10 +54,15 @@ macOS 15.4 introduced a developer-preview pasteboard-privacy prompt. The backend
 - **Watcher & `availableFormats()`** — use `changeCount` and `-types`, both of which return metadata only. **No prompt.**
 - **`readXxx` methods** — read actual bytes; will trigger the prompt when `defaults write <bundle-id> EnablePasteboardPrivacyDeveloperPreview -bool yes` is active, or on macOS 16 when the prompt is enabled by default.
 - **`Clipboard.setAccessBehavior(...)`** — maps to `NSPasteboard.accessBehavior` (macOS 15.4+, guarded by `respondsToSelector:`). Older macOS versions silently ignore the call.
+- **`Clipboard.accessBehavior`** — reads the currently effective policy. Returns `null` when the runtime is older than macOS 15.4 (treat as unrestricted).
+- **`Clipboard.isAccessBehaviorSupported`** — `true` when both getter and setter selectors respond on `NSPasteboard`. Use this to gate UI that lets the user pick a policy.
 
 ```kotlin
 // At startup — opt the app into "ask every time" policy on macOS 15.4+.
-Clipboard.setAccessBehavior(AccessBehavior.AskEveryTime)
+if (Clipboard.isAccessBehaviorSupported) {
+    Clipboard.setAccessBehavior(AccessBehavior.AskEveryTime)
+    println("Effective policy: ${Clipboard.accessBehavior}")
+}
 ```
 
 ## Concealed / transient content

example/src/main/kotlin/com/example/demo/ClipboardScreen.kt

@@ -38,6 +38,7 @@ import androidx.compose.ui.graphics.painter.BitmapPainter
 import androidx.compose.ui.graphics.toComposeImageBitmap
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.unit.dp
+import io.github.kdroidfilter.nucleus.clipboard.AccessBehavior
 import io.github.kdroidfilter.nucleus.clipboard.Clipboard
 import io.github.kdroidfilter.nucleus.clipboard.ClipboardEvent
 import io.github.kdroidfilter.nucleus.clipboard.ClipboardFormat
@@ -103,6 +104,12 @@ fun ClipboardScreen() {
             )
 
             WatcherCard(currentFormats, currentChangeCount)
+            AccessBehaviorCard(
+                onChange = { behavior ->
+                    Clipboard.setAccessBehavior(behavior)
+                    log("access behavior → $behavior")
+                },
+            )
             WriteCard(
                 textToCopy = textToCopy,
                 onTextChange = { textToCopy = it },
@@ -221,6 +228,47 @@ private fun WatcherCard(
     }
 }
 
+@Composable
+private fun AccessBehaviorCard(onChange: (AccessBehavior) -> Unit) {
+    val supported = Clipboard.isAccessBehaviorSupported
+    var current by remember { mutableStateOf(Clipboard.accessBehavior) }
+
+    Card(colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.surfaceContainerLow)) {
+        Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(8.dp)) {
+            Text("Privacy — macOS 15.4+", style = MaterialTheme.typography.titleMedium)
+            Text(
+                if (supported) {
+                    "current: ${current?.name ?: "(unknown)"}"
+                } else {
+                    "Not supported on this OS / runtime — reads are unrestricted."
+                },
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                fontFamily = FontFamily.Monospace,
+            )
+            Row(horizontalArrangement = Arrangement.spacedBy(6.dp)) {
+                AccessBehavior.entries.forEach { behavior ->
+                    FilterChip(
+                        enabled = supported,
+                        selected = current == behavior,
+                        onClick = {
+                            onChange(behavior)
+                            current = Clipboard.accessBehavior
+                        },
+                        label = { Text(behavior.name) },
+                    )
+                }
+            }
+            Text(
+                "Watcher and availableFormats() only read metadata " +
+                    "(changeCount + types) — they never trigger the pasteboard-privacy prompt.",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+    }
+}
+
 @Composable
 private fun WriteCard(
     textToCopy: String,