Skip to main content

Overview

QuickLookCoordinator manages the system Quick Look panel, allowing users to preview files directly from R2 storage without downloading them first. It streams files using presigned URLs and integrates with macOS’s native Quick Look functionality (spacebar preview).
Located at: Fiaxe/Services/QuickLookCoordinator.swift:18

Type Definition

Main actor-isolated singleton that implements Quick Look protocols for preview functionality.

Singleton Instance

Access the shared coordinator instance from the main actor.

Methods

preview()

Displays the Quick Look panel for a specific R2 object.
R2Object
required
The R2 object to preview. Must contain a valid key and name.
R2Credentials
required
R2 credentials used to generate a presigned URL for secure access.

Implementation Details

The method:
  1. Gets the shared Quick Look panel
  2. Toggles panel visibility if already open for the same coordinator
  3. Generates a presigned URL for streaming the file directly from R2
  4. Wraps the URL in a PreviewItem with the filename for proper format detection
  5. Sets itself as the data source and delegate
  6. Shows the panel and loads the preview
No Download RequiredQuick Look streams the file directly from the presigned URL without downloading to disk first. This provides instant previews for files of any size.

Preview Item Wrapper

The coordinator uses a private PreviewItem class to wrap URLs for Quick Look:
URL?
The presigned URL pointing to the R2 object.
String?
The original filename. Quick Look uses this to determine the correct previewer plugin based on file extension.
Why Wrap the URL?URL is a struct and can’t directly conform to the QLPreviewItem protocol which requires NSObject. The wrapper class provides this conformance.

Protocol Conformance

QLPreviewPanelDataSource

Provides preview items to the Quick Look panel.

numberOfPreviewItems()

Returns 1 if a preview item is available, 0 otherwise.

previewPanel(_:previewItemAt:)

Returns the current preview item at the specified index.

QLPreviewPanelDelegate

Handles Quick Look panel events.

previewPanel(_:handle:)

Returns false to use default event handling. Could be customized for keyboard shortcuts or gestures.

Presigned URL Generation

The coordinator relies on AWSV4Signer to generate time-limited presigned URLs:
Presigned URLs:
  • Grant temporary read access to private R2 objects
  • Expire after a set duration (typically 1 hour)
  • Allow streaming without exposing credentials
  • Work with any HTTP client (including Quick Look)

Supported File Types

Quick Look supports previews for many file types:

Images

JPEG, PNG, GIF, HEIC, SVG, etc.

Videos

MP4, MOV, M4V, etc.

Documents

PDF, Pages, Word, Excel, etc.

Code

Swift, Python, JavaScript, etc.

Archives

ZIP, TAR, etc. (shows contents)

Audio

MP3, M4A, FLAC, etc.

Usage Example

Toggle Behavior

The coordinator implements smart toggle behavior:
This allows users to:
  • Press spacebar to open preview
  • Press spacebar again to close preview
  • Switch between different files seamlessly

Integration with r2Vault

In the main browser view, Quick Look is triggered via:
Users can:
  • Select a file and press spacebar
  • Double-click a file (if implemented)
  • See instant previews without downloading

Performance Characteristics

Files are streamed directly from R2 via presigned URLs. Quick Look handles buffering and caching automatically.
Previews don’t write to disk (unless Quick Look caches internally). Large files can be previewed without filling up storage.
Preview quality depends on network speed. Slow connections may show loading indicators.

Limitations

Quick Look Limitations
  • Some file types may not be supported
  • Very large files (multi-GB) may timeout or be slow to load
  • Network interruptions will break the preview
  • Presigned URLs expire after their validity period
  • Private R2 buckets require valid credentials

Security Considerations

Presigned URL SecurityPresigned URLs are temporary and scoped to a single object:
  • URLs expire after a set duration (typically 1 hour)
  • Each URL is signed with credentials
  • URLs grant read-only access to one specific file
  • No credentials are exposed to Quick Look or the user
  • URLs can’t be used to access other files
This is secure for personal use cases where you control the R2 bucket.