# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ScreenDump is a VNC server for jailbroken iOS 15+ devices (rootless/Ellekit). It captures the device screen and streams it via VNC protocol while supporting remote keyboard and touch input.

## Build Commands

```bash
# Build the package (requires Theos installed)
make package

# Clean build artifacts
make clean

# Build and install to device (requires SSH access)
make package install THEOS_DEVICE_IP=<device-ip>
```

The build produces `screendumpd` daemon installed to `/usr/libexec`.

## Architecture

### Core Components

- **ScreenDumpVNC** ([ScreenDumpVNC.m](ScreenDumpVNC.m)) - Main singleton controller that:
  - Initializes libvncserver with screen dimensions
  - Manages IOSurface framebuffer acquisition via IOMobileFramebuffer
  - Creates IOSurfaceAccelerator for frame scaling/transfer
  - Handles dual capture mode switching

- **FrameUpdater** ([FrameUpdater.m](FrameUpdater.m)) - Frame capture loop:
  - Runs on NSOperationQueue with max 1 concurrent operation (serialized)
  - Uses CADisplayLink for vsync-based updates at 60fps
  - Transfers frames via IOSurfaceAcceleratorTransferSurface or CARenderServerRenderDisplay

- **VNC Event Handlers** ([vnc.m](vnc.m)) - Input injection:
  - Keyboard events via IOHIDEventSystemClient (XK keysym to HID usage mapping)
  - Touch/pointer via IOHIDDigitizer events (normalized coordinates)
  - Backslash key (`\`) toggles capture mode

### Capture Modes

Two capture modes available, toggled via backslash key during VNC session:

1. **CARenderServer** (default) - Uses `CARenderServerRenderDisplay()`, faster but hides secure text fields
2. **IOMobileFramebuffer** (legacy) - Direct framebuffer access, shows password fields but auto-reverts after 10 seconds

### Frame Pipeline

```
IOMobileFramebuffer → screenSurface (native res)
                           ↓
              [CARenderServer or direct transfer]
                           ↓
         renderServerSurface (if scaling needed)
                           ↓
            IOSurfaceAccelerator transfer
                           ↓
              staticBuffer (VNC output res)
                           ↓
            rfbMarkRectAsModified → VNC clients
```

### Dependencies

Pre-built libraries in `vncbuild/`:
- libvncserver (VNC protocol)
- libpng, libjpeg (image encoding)
- libssl, libcrypto (VNC authentication)

## Configuration

User preferences read from `com.mousen.screendump` preference domain:
- `enabled` - Enable/disable daemon
- `width`, `height` - Custom output resolution (maintains aspect ratio, aligns to 4px)
- `password` - VNC authentication password

## Entitlements

[en.plist](en.plist) contains required entitlements for:
- IOSurface/IOMobileFramebuffer access
- HID event dispatch (input injection)
- QuartzCore global capture
