Paperand Development Skill

This skill provides comprehensive guidance for working with the Paperand project - an ad-free manga reader built with Expo and React Native, compatible with Paperback extensions.

Project Overview

Paperand is a cross-platform manga reader app that:

• Provides an elegant, ad-free manga reading experience
• Is compatible with Paperback extension sources
• Supports both Android and iOS platforms
• Features a personal library, reading progress tracking, and multi-source search

Tech Stack

Technology	Purpose
Expo SDK 54	Development framework
React Native 0.81	Cross-platform mobile development
TypeScript	Type-safe JavaScript
React Navigation 7	Navigation library (stack + bottom tabs)
AsyncStorage	Persistent local storage
expo-image	Optimized image loading with caching
WebView	Extension runtime for Paperback sources
i18n-js	Internationalization

Project Structure

paperback-android/
├── App.tsx                    # Main app entry, providers setup
├── index.ts                   # Expo entry point
├── app.json                   # Expo configuration
├── package.json               # Dependencies
├── src/
│   ├── components/            # Reusable UI components
│   │   ├── MangaCard.tsx      # Manga cover card component
│   │   ├── ChapterListItem.tsx # Chapter list item
│   │   ├── ExtensionRunner.tsx # WebView extension runtime
│   │   ├── PickerModal.tsx    # Custom picker modal
│   │   └── ...
│   ├── context/               # React Context providers
│   │   ├── ThemeContext.tsx   # Theme management
│   │   └── LibraryContext.tsx # Library & progress state
│   ├── navigation/            # Navigation configuration
│   │   ├── AppNavigator.tsx   # Main stack navigator
│   │   └── BottomTabNavigator.tsx # Bottom tab navigation
│   ├── screens/               # App screens
│   │   ├── LibraryScreen.tsx  # User library
│   │   ├── DiscoverScreen.tsx # Browse sources
│   │   ├── SearchScreen.tsx   # Multi-source search
│   │   ├── MangaDetailScreen.tsx # Manga details & chapters
│   │   ├── ReaderScreen.tsx   # Manga reader (core feature)
│   │   ├── DownloadManagerScreen.tsx # Download management
│   │   ├── ExtensionsScreen.tsx # Manage extensions
│   │   └── ...
│   ├── services/              # Core business logic
│   │   ├── sourceService.ts   # Extension API bridge
│   │   ├── extensionService.ts # Extension management
│   │   ├── cacheService.ts    # Image caching
│   │   ├── downloadService.ts # Chapter downloads
│   │   ├── themeService.ts    # Theme file parsing
│   │   ├── i18nService.ts     # Internationalization
│   │   ├── updateService.ts   # App update checks
│   │   └── ...
│   ├── hooks/                 # Custom React hooks
│   ├── types/                 # TypeScript type definitions
│   ├── constants/             # App constants
│   └── locales/               # Translation files (17 languages)
├── android/                   # Android native code
├── assets/                    # Images, icons, fonts
├── plugins/                   # Custom Expo config plugins
└── credentials/               # Build credentials

Development Commands

# Install dependencies
npm install
# or
bun install

# Start development server
npx expo start

# Run on Android
npm run android

# Run on iOS
npm run ios

# Run on web
npm run web

Key Architectural Patterns

1. Extension System

The app uses a WebView-based extension runtime (ExtensionRunner.tsx) to execute Paperback-compatible extensions. Extensions are JavaScript bundles that provide manga source implementations.

2. Context Providers

• ThemeContext: Manages app theme (dark/light mode) and custom .pbcolors themes
• LibraryContext: Manages user library, favorites, reading progress, and history

3. Service Layer

All business logic is encapsulated in service files:

• sourceService.ts - Bridge between app and extensions
• cacheService.ts - Image caching with configurable limits
• downloadService.ts - Background chapter downloads
• i18nService.ts - Multi-language support

4. Navigation Structure

Stack Navigator (AppNavigator)
├── Bottom Tab Navigator
│   ├── Library
│   ├── Discover
│   ├── History
│   └── More
├── MangaDetail
├── Reader
├── Search
├── Extensions
├── Settings
└── ...

Internationalization (i18n)

The app supports 17+ languages. Translation files are in src/locales/ as JSON files.

Adding a new translation:

1. Create a new JSON file in src/locales/ (e.g., de.json)
2. Copy the structure from en.json
3. Translate all strings
4. Register the language in i18nService.ts

Theming

The app supports custom themes via .pbcolors files (Paperback theme format).

Theme configuration:

• System theme support (automatic dark/light mode)
• Custom color parsing in themeService.ts
• Theme application via ThemeContext

Building for Production

GitHub Actions (Automated)

On push to main or manual trigger:

1. Builds Android APK with signing
2. Builds iOS IPA
3. Creates GitHub Release with artifacts

Local EAS Build

# Android APK
eas build --platform android --profile preview

# iOS
eas build --platform ios --profile preview

Common Development Tasks

Adding a New Screen

1. Create the screen component in src/screens/
2. Export it from src/screens/index.ts
3. Add the route in src/navigation/AppNavigator.tsx
4. Add navigation types if using TypeScript

Adding a New Component

1. Create the component in src/components/
2. Export it from src/components/index.ts
3. Use the theme from ThemeContext for styling

Adding a New Service

1. Create the service file in src/services/
2. Use AsyncStorage for persistent data
3. Follow existing patterns for async operations

Code Style Guidelines

• Use TypeScript for all new files
• Use functional components with hooks
• Use the app's theme system for colors (useTheme())
• Use i18n.t('key') for all user-facing strings
• Keep components focused and reusable
• Use services for business logic, not in components

Testing & Debugging

• Developer Menu: Tap version number in More > About 7 times
• Console Logging: Use standard console.log (visible in Metro bundler)
• React Native Debugger: Connect via Expo dev tools

Important Notes

• The app uses Expo managed workflow with custom native code via config plugins
• Background downloads require foreground service configuration (Android)
• Extension execution happens in an isolated WebView context
• Image caching is handled by expo-image with custom cache management

---

Quick Reference

Import Patterns

// Theme & Styles
import { useTheme } from '../context/ThemeContext';

// Library & State
import { useLibrary } from '../context/LibraryContext';

// Navigation
import { useNavigation, useRoute } from '@react-navigation/native';

// Components
import { MangaCard, LoadingIndicator, EmptyState } from '../components';

// Services
import { sourceService } from '../services/sourceService';
import { cacheService } from '../services/cacheService';

// i18n
import { i18n } from '../services/i18nService';

Screen Template

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { useTheme } from '../context/ThemeContext';

export function NewScreen() {
  const { colors } = useTheme();
  
  return (
    <View style={[styles.container, { backgroundColor: colors.background }]}>
      {/* Content */}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});

Navigation Params

// Navigate with params
navigation.navigate('MangaDetail', { manga, sourceId });
navigation.navigate('Reader', { manga, chapter, sourceId });

// Get params
const { manga, sourceId } = useRoute().params;

---

Styling Patterns

Theme Colors

const { colors, isDark } = useTheme();
// colors.background, colors.text, colors.primary, colors.card, colors.border

Common Styles

// Card style
{ backgroundColor: colors.card, borderRadius: 12, padding: 16 }

// Text styles
{ color: colors.text, fontSize: 16 }
{ color: colors.textSecondary, fontSize: 14 }

// Separator
{ height: 1, backgroundColor: colors.border }

---

State Management

Library Context Methods

const { 
  library,           // Manga[] - saved manga
  favorites,         // string[] - favorite manga IDs
  readingProgress,   // { [mangaId]: { chapterId, page } }
  addToLibrary,      // (manga) => void
  removeFromLibrary, // (mangaId) => void
  toggleFavorite,    // (mangaId) => void
  updateProgress,    // (mangaId, chapterId, page) => void
} = useLibrary();

AsyncStorage Keys

Key	Type	Description
@library	Manga[]	Saved manga
@favorites	string[]	Favorite IDs
@reading_progress	object	Reading positions
@extensions	Extension[]	Installed extensions
@settings	object	User settings
@history	HistoryItem[]	Reading history

---

Extension API

Source Service Methods

// Get manga list
await sourceService.getDiscoverSection(sourceId, sectionId);

// Search manga
await sourceService.searchManga(sourceId, query);

// Get manga details
await sourceService.getMangaDetails(sourceId, mangaId);

// Get chapters
await sourceService.getChapters(sourceId, mangaId);

// Get chapter pages
await sourceService.getChapterPages(sourceId, chapterId);

---

Error Handling

try {
  const data = await sourceService.getMangaDetails(sourceId, mangaId);
} catch (error) {
  console.error('Failed to load manga:', error);
  // Show error state or toast
}

---

Performance Tips

1. Images: Use expo-image with cachePolicy="memory-disk"
2. Lists: Use FlatList with keyExtractor and getItemLayout
3. Memoization: Use useMemo/useCallback for expensive operations
4. Lazy Loading: Load chapters/pages on demand

---

File Naming

Type	Convention	Example
Screen	*Screen.tsx	LibraryScreen.tsx
Component	PascalCase.tsx	MangaCard.tsx
Service	*Service.ts	cacheService.ts
Hook	use*.ts	useDebounce.ts
Context	*Context.tsx	ThemeContext.tsx
Types	index.ts	types/index.ts

---

Troubleshooting

Issue	Solution
Extension not loading	Check WebView logs, verify extension URL
Images not caching	Check cache size limits in settings
Build fails	Run npx expo prebuild --clean
Metro bundler stuck	Clear cache: npx expo start -c
Android foreground service crash	Check withBackgroundActionsServiceType plugin

---

Android-Specific

• Foreground service type configured in plugins/withBackgroundActionsServiceType.js
• Permissions in app.json under android.permissions
• Deep links: paperback:// and paperand:// schemes

iOS-Specific

• Background modes: fetch enabled
• Localization: 35+ locales in CFBundleLocalizations
• Bundle ID: com.chiraitori.paperand.ios