ReframeICloudKit.git · README.md

revision a10e1287dd6251b9120f0825b43a74a0b57819d5 · complete file
# ReframeICloudKit

`ReframeICloudKit` is the Fountain-Coach Kit for placing and referencing visual material through two honest Apple
boundaries:

```text
native Photos library  → PhotoKitBackend       → completed placement receipt
iCloud.com session     → ICloudWebBackend      → embedded session + observable handoff
```

The public API is unified, while the capabilities remain distinct. PhotoKit can create an asset and add it to an
album using Apple’s supported `PHPhotoLibrary` change requests. The WebKit route exists for accounts whose desired
cloud library is not exposed by the accepted macOS Photos configuration. It supplies a staged file to Apple’s visible
upload chooser; the host must observe and report the page’s completion before recording placement.

```swift
let request = ICloudPlacementRequest(
    sourceFile: generatedPNG,
    albumTitle: "Image_gen",
    lineageID: promptID
)

let result = try await ReframeICloudKit().place(request, using: .photoKit)
```

`staged`, `awaitingUser`, `blocked`, `placed`, and `failed` are different outcomes. The kit never converts a staged
file or a displayed web page into a false success.

## Boundary

This package does not implement Apple’s private iCloud Photos service. It does not automate undocumented endpoints,
capture Apple passwords, inspect Photos’ database, or control an arbitrary external `.photoslibrary`. WebKit is an
embedded transport surface, not the application’s visual shell.

## Requirements

- macOS 14 or later
- a signed host application with the required Photos usage declaration for PhotoKit
- a user-approved Photos authorization for the native route
- a host-provided AX and visible-state observer for WebKit completion

## FCIS status

The package is source-published as a Fountain-Coach Kit. Release tags, API compatibility, and host acceptance belong
to this repository; Reframe consumes a released package revision rather than copying the implementation.