upstream-affine/packages/frontend/apps/ios/AGENTS.md

# CLAUDE.md

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

## Project Overview

This is the AFFiNE iOS application built with Capacitor, React, and TypeScript. It's a hybrid mobile app that wraps a React web application in a native iOS shell.

## Development Commands

### Build and Development

- `yarn dev` - Start development server with live reload
- `yarn build` - Build the web application
- `yarn sync` - Sync web assets with Capacitor iOS project
- `yarn sync:dev` - Sync with development server (CAP_SERVER_URL=http://localhost:8080)
- `yarn xcode` - Open Xcode project
- `yarn codegen` - Generate GraphQL and Rust bindings
- `xcodebuild -workspace App.xcworkspace -scheme App -destination 'platform=iOS Simulator,name=iPhone 15' build | xcbeautify` - Build iOS project with xcbeautify

### iOS Build Process

1. `BUILD_TYPE=canary PUBLIC_PATH="/" yarn affine @affine/ios build` - Build web assets
2. `yarn affine @affine/ios cap sync` - Sync with iOS project
3. `yarn affine @affine/ios cap open ios` - Open in Xcode

### Live Reload Setup

1. Run `yarn dev` and select `ios` for Distribution option
2. Run `yarn affine @affine/ios sync:dev`
3. Run `yarn affine @affine/ios cap open ios`

## Architecture

### Core Technologies

- **Capacitor 7.x** - Native iOS bridge
- **React 19** - UI framework
- **TypeScript** - Language
- **Blocksuite** - Document editor
- **DI Framework** - Dependency injection via `@toeverything/infra`

### Key Directories

- `src/` - React application source
- `App/` - Native iOS Swift code
- `dist/` - Built web assets
- `capacitor-cordova-ios-plugins/` - Capacitor plugins

### Native Bridge Integration

The app exposes JavaScript APIs to native iOS code through `window` object:

- `getCurrentServerBaseUrl()` - Get current server URL
- `getCurrentI18nLocale()` - Get current locale
- `getAiButtonFeatureFlag()` - Check AI button feature flag
- `getCurrentWorkspaceId()` - Get current workspace ID
- `getCurrentDocId()` - Get current document ID
- `getCurrentDocContentInMarkdown()` - Export current doc as markdown
- `createNewDocByMarkdownInCurrentWorkspace()` - Import markdown as new doc

### Swift Code Style

Follow the guidelines in `AGENTS.md`:

- 2-space indentation
- PascalCase for types, camelCase for properties/methods
- Modern Swift features: `@Observable`, `async/await`, `actor`
- Protocol-oriented design, dependency injection
- Early returns, guard statements for optional unwrapping

### Build Configuration

- TypeScript config extends `../../../../tsconfig.web.json`
- Webpack bundling via `@affine-tools/cli`
- Capacitor config in `capacitor.config.ts`
- GraphQL codegen via Apollo
- Rust bindings generated via Uniffi

### Dependencies

- Workspace packages: `@affine/core`, `@affine/component`, `@affine/env`
- Capacitor plugins: App, Browser, Haptics, Keyboard
- React ecosystem: React Router, Next Themes
- Storage: IDB, Yjs for collaborative editing

### Testing and Quality

- TypeScript strict mode enabled
- Oxlint/Oxfmt configuration from workspace root
- No specific test commands in this package (tests likely in workspace root)

# Swift Code Style Guidelines

## Core Style

- **Indentation**: 2 spaces
- **Braces**: Opening brace on same line
- **Spacing**: Single space around operators and commas
- **Naming**: PascalCase for types, camelCase for properties/methods

## File Organization

- Logical directory grouping
- PascalCase files for types, `+` for extensions
- Modular design with extensions

## Modern Swift Features

- **@Observable macro**: Replace `ObservableObject`/`@Published`
- **Swift concurrency**: `async/await`, `Task`, `actor`, `@MainActor`
- **Result builders**: Declarative APIs
- **Property wrappers**: Use line breaks for long declarations
- **Opaque types**: `some` for protocol returns

## Code Structure

- Early returns to reduce nesting
- Guard statements for optional unwrapping
- Single responsibility per type/extension
- Value types over reference types

## Error Handling

- `Result` enum for typed errors
- `throws`/`try` for propagation
- Optional chaining with `guard let`/`if let`
- Typed error definitions

## Architecture

- Avoid using protocol-oriented design unless necessary
- Dependency injection over singletons
- Composition over inheritance
- Factory/Repository patterns

## Debug Assertions

- Use `assert()` for development-time invariant checking
- Use `assertionFailure()` for unreachable code paths
- Assertions removed in release builds for performance
- Precondition checking with `precondition()` for fatal errors

## Memory Management

- `weak` references for cycles
- `unowned` when guaranteed non-nil
- Capture lists in closures
- `deinit` for cleanup