FileKit

PlatformFile is the core Kotlin Multiplatform abstraction for file operations. It provides a consistent API across all platforms and is interoperable with kotlinx-io.

You can obtain a PlatformFile via dialogs, or by using the division operator on standard directory paths.

Common Properties and Methods:

• name: The file name.
• extension: The file extension.
• path: The file path.
• size(): Returns the size in bytes.
• absolutePath(): Returns the absolute path.
• exists(): Checks if the file exists.
• isRegularFile(): Checks if it is a file.
• isDirectory(): Checks if it is a directory.
• parent(): Returns the parent PlatformFile.

File Operations:

• createDirectories(): Creates necessary directories.
• copyTo(destinationFile): Copies the file.
• atomicMove(destinationFile): Moves the file atomically.
• delete(): Deletes the file.

// Pick a file
val file = FileKit.openFilePicker()

// Get a file reference
val file = FileKit.filesDir / "document.pdf"

// Get the file properties
val name: String = file.name
val extension: String = file.extension
val path: String = file.path
val size: Long = file.size()
val absolutePath: String = file.absolutePath()
val parent: PlatformFile? = file.parent()
val exists: Boolean = file.exists()
val isFile: Boolean = file.isRegularFile()
val isDirectory: Boolean = file.isDirectory()

// File operations
file.createDirectories()
file.copyTo(destinationFile)
file.atomicMove(destinationFile)
file.delete()

This record describes the technical resolution for Issue #626, which addresses crashes on macOS/JVM when multiple dependencies attempt to register an Objective-C class named IdeaRunnable. Because Objective-C class names occupy a process-wide namespace, collisions with other libraries (like IntelliJ/JBR) cause objc_allocateClassPair to return Nil or a zero-valued ID.

To resolve this, FileKit implements the following safety measures:

1. Namespace Isolation: Uses a unique, prefixed name FileKitMainThreadRunnable instead of the generic IdeaRunnable.
2. Defensive Allocation: Explicitly checks for both Kotlin null and zero-valued ID results using Foundation.isNil. If allocation fails, it throws an IllegalStateException immediately.
3. Safe Lifecycle Management: Follows the strict Apple-recommended sequence: allocate $\rightarrow$ add method (run:) $\rightarrow$ register. If class_addMethod fails, the unregistered class is cleaned up using objc_disposeClassPair to prevent memory leaks or incomplete class states.
4. Explicit Ownership: Instead of performing a global getObjcClass(name) lookup (which could return a foreign class), FileKit stores the specific class ID and the JNA Callback reference in a private support value during a single, locked initialization phase.

FileKit uses a platform-specific abstraction called Bookmark Data to provide cross-platform references to user-selected files while respecting platform security models (like macOS sandboxing).

Key concepts to understand for managing file references:

• Bookmark Data: An opaque, platform-specific persistent reference. It is not portable between platforms and should not be treated as a simple saved path or serialized file. It may preserve access grants.
• Security-Scoped Bookmark: Specifically for macOS, this preserves sandbox access to a resource across application launches.
• Bookmark Resolution: The process of interpreting stored bookmark data to recover a PlatformFile. Note that successful resolution identifies the resource but does not guarantee that subsequent file operations will succeed.
• Access Capability: The authority granted by the platform to a PlatformFile to access a resource. For directories, this capability extends to files within that directory.
• Scoped Access: The bounded period during which an application must actively use/activate the access represented by a security-scoped resource.
• Stale Bookmark: A bookmark that is still resolvable but should be replaced with newly created bookmark data according to the platform. This is different from an invalid bookmark.
• Legacy Bookmark Data: Data created by older FileKit behaviors that may not preserve current access guarantees. FileKit attempts to resolve these permissively.
• Bookmark Refresh: An advisory action to replace successfully resolved bookmark data when the platform reports it as stale or FileKit identifies it as legacy. This preserves or upgrades the reference but cannot recover access already revoked by the OS.

On platforms with sandboxing (Android, iOS, macOS), standard file paths may become invalid after an app restart. BookmarkData provides a way to create a persistent, secure reference to a file that can be saved (e.g., to preferences or a database) and used later to reliably regain access.

Basic Workflow:

1. Create: Call .bookmarkData() on a PlatformFile to get the bytes representing the bookmark.
2. Save: Store these bytes in your application's persistent storage.
3. Load: Retrieve the bytes from storage.
4. Restore: Use PlatformFile.fromBookmarkData(bytes) to recreate the PlatformFile object.

// 1. User picks a file
val userPickedFile: PlatformFile = // ...from a file picker

// 2. Create and save its bookmark data
val bookmark = userPickedFile.bookmarkData()
MyPreferences.save("last_file_bookmark", bookmark.bytes)

// --- App restarts ---

// 3. Load the saved bookmark data
val savedBytes = MyPreferences.load("last_file_bookmark")

// 4. Restore the PlatformFile from the bookmark
if (savedBytes != null) {
    val restoredFile = PlatformFile.fromBookmarkData(savedBytes)
    // Now you can work with the restoredFile
}

When working with FileKit on macOS JVM, specific terminology is used to distinguish between work and state owned by a FileKit runtime versus state owned by other parts of the process. Use these terms to avoid confusion when debugging or extending the library:

• Runnable Adapter: A FileKit-owned bridge that carries a JVM runnable ticket onto the macOS application thread. (Do not confuse with IdeaRunnable or global helpers).
• Runnable Ticket: An opaque identifier that connects a scheduled main-thread callback to its corresponding JVM work. (Do not confuse with Runnable pointer or callback state).
• Foreign Adapter: A main-thread bridge owned by code outside the current FileKit runtime owner, even if it seems compatible. (Do not confuse with Reusable adapter or shared helper).
• Runtime Owner: The specific FileKit runtime instance that owns one runnable adapter and its pending runnable tickets as a single lifecycle. (Do not confuse with Global helper or shared adapter).