> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridshift.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Companion

> Browse Gridshift projects from iPhone or iPad, preview saved version bounces, and manage tasks from the companion app.

The iOS Companion lets you browse Gridshift projects stored in iCloud Drive from your iPhone or iPad. It reads a lightweight `manifest.json` written by the Mac app, so the project list can load project metadata, artwork thumbnails, track summaries, and version previews without opening the full `project.json` first.

## Requirements

* iPhone or iPad running **iOS / iPadOS 18.0** or later
* The same Apple ID as your Mac, with **iCloud Drive** enabled
* Gridshift on macOS saving projects into the shared Gridshift iCloud container
* At least one saved version with a bounce preview if you want instant playback from the project list

## Project List

Projects are grouped by workflow status in horizontal carousels. Pull to refresh rescans iCloud, and if iCloud is unavailable the companion shows an explicit unavailable state instead of a stale local cache.

Tap a project cover to control browsing playback:

* **New project:** shows the mini player and starts the newest saved version that has a bounce preview
* **Currently playing project:** tapping the same cover pauses playback
* **Paused project:** tapping the same cover resumes playback
* **Different project:** switches playback and updates the mini player to the newly selected project

You can also drag a project card between status sections to update its workflow state from iOS.

## Mini Player Bar

The mini player appears at the bottom of the project list after you select a project. It includes:

* project artwork thumbnail
* a progress strip across the top edge
* elapsed time / total time while a bounce is active
* a play/pause control

Tap the **mini player bar** to expand into the full project detail view. Tap the **project artwork in the list** to pause/resume or switch playback.

If the selected project has no active bounce preview yet, the bar stays visible and shows the project's BPM until a playable version is available.

## Detail View

Expanding the mini player opens a full-height detail sheet with:

* a large artwork header with project name, tempo, and description
* a **Versions** tab for saved version previews and bounce playback
* a **Tasks** tab backed by the shared `tasks.json`, so task changes sync between macOS and iOS

Bounce previews download from iCloud on demand. While a preview file is still being fetched, the mini player switches to a **Downloading...** state and starts playback automatically once the file becomes local.

## Delete Flow

Long-press a project card to open a context menu with artwork preview and a delete action. Choosing **Delete from iCloud** asks for confirmation before removing the entire `.gsp` bundle from the shared iCloud container.

That delete removes the project, its saved versions, and its bounce previews from iCloud. If the deleted project is currently active in the mini player, playback stops immediately and the mini player closes.

## iCloud Notes

The companion app is designed around iCloud-backed projects:

* project browsing uses the Gridshift iCloud container
* manifests are read first for fast list loading
* older projects without `manifest.json` fall back to `project.json`
* task edits are written cross-platform via `tasks.json`

For more about the shared storage layout, see [iCloud](/features/icloud).