> For the complete documentation index, see [llms.txt](https://docs.tatakai.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tatakai.me/feature-guides/manga-reader.md).

# Manga reader

Tatakai's manga reader supports vertical scroll (webtoon), paged (manga), and spread views with extensive customization, multi-source aggregation, and offline reading.

***

## Architecture

```
MangaReader (React)
├── MangaViewer (canvas/img rendering)
├── Virtualized chapter list
├── Extension bridge (manga-extension-runtime.ts)
├── Progress tracking (Supabase + local)
└── Settings panel (reading modes, appearance)
```

**Key Files:**

* `src/features/manga/components/MangaReader.tsx`
* `src/features/manga/components/MangaViewer.tsx`
* `src/core/content/manga-extension-runtime.ts`
* `src/hooks/user/useMangaReadlist.ts`

***

## Reading Modes

| Mode                | Description                  | Best For                      |
| ------------------- | ---------------------------- | ----------------------------- |
| **Vertical Scroll** | Continuous infinite scroll   | Webtoons, manhwa, long strips |
| **Paged (LTR)**     | Left-to-right page turns     | Traditional manga             |
| **Paged (RTL)**     | Right-to-left page turns     | Japanese manga                |
| **Spread**          | Two-page spreads (landscape) | Double-page art               |
| **Fit Width**       | Scale to container width     | All modes                     |

**Switch:** `V` key or toolbar button.

***

## Source Aggregation

### Multi-Source Chapters

```
Manga Detail Page
        │
        ▼
manga-extension-runtime.ts
        │
        ├── Fans out to ALL extensions with `manga` capability
        │
        ▼
Each extension → GET /api/v3/<ns>/manga/chapters
        │
        ▼
Host flattens → one row per (chapter, sub-provider)
        │
        ▼
Merge by chapter number → deduplicate
        │
        ▼
UI shows: Chapter 1 [MangaDex, MangaKakalot, AsuraScans]
```

### Sub-Provider → Namespace Mapping

```ts
// Lazy map populated during chapter fetch
const subProviderToNamespace = new Map<string, string>();
// "mangadex" → "toko"
// "allmanga" → "mangadex-ext"
```

Used for pages request routing.

***

## Chapter List

### Features

* **Grouped by volume** (collapsible)
* **Language badges** (🇺🇸 EN, 🇯🇵 JP, 🇰🇷 KR, etc.)
* **Scanlator tags** (Official, Fan Group)
* **Release date** sorting
* **Read/unread indicators** (progress sync)
* **Download buttons** per chapter
* **Batch download** (volume/arc/all)

### Filtering

* Language (multi-select)
* Scanlator (multi-select)
* Volume (dropdown)
* Status: Unread / Reading / Read

***

## MangaViewer

### Rendering

| Mode         | Implementation                                                    |
| ------------ | ----------------------------------------------------------------- |
| **Vertical** | `<img>` with `loading="lazy"`, `IntersectionObserver` for preload |
| **Paged**    | Horizontal scroll snap, one page per viewport                     |
| **Spread**   | Two images side-by-side, center gap                               |

### Page Loading

```ts
// Pages fetched via GET /api/v3/<ns>/manga/pages?chapterKey=...
// Each page image proxied via localProxy (headers replayed)
// Returns: { pages: [{ pageNumber, imageUrl, proxiedImageUrl, headers }] }
```

### Controls

| Control          | Key             | Touch             |
| ---------------- | --------------- | ----------------- |
| Next page        | → / Space       | Swipe left        |
| Previous page    | ← / Shift+Space | Swipe right       |
| Next chapter     | `N`             | Long press → next |
| Previous chapter | `B`             | Long press → prev |
| Toggle mode      | `V`             | Toolbar           |
| Zoom             | `+/-` / wheel   | Pinch             |
| Fit width        | `F`             | Double tap        |

***

## Progress & Sync

### Local Progress

* **Page index** (vertical: scroll position, paged: page number)
* **Chapter completion** (auto-mark at 90% scroll)
* **Per-chapter timestamps** (last read position)

### Cross-Device Sync

```ts
// Supabase tables
read_progress {
  user_id, media_type ('manga'), source_id, chapter_id,
  page_index, scroll_offset, completed, updated_at
}

// Synced via:
// 1. Real-time on app focus
// 2. Background sync (desktop)
// 3. Manual "Sync Now" in Settings
```

### AniList/MAL/MangaBaka Sync

* **Bidirectional** — local ↔ external
* **Matching:** AniList ID → MangaBaka ID → MAL ID
* **Conflict resolution:** Last-write-wins with timestamp

***

## Offline Reading

### Download

```ts
// Queue chapter for download
await downloadManager.queue({
  type: 'manga',
  sourceId: 'mangadex',        // sub-provider
  namespace: 'toko',           // extension namespace
  chapterKey: 'md:ch-123',
  title: 'Chapter 123',
  quality: 'original',         // or 'compressed'
});
```

### Offline Library

* **Settings → Downloads → Manga** — lists all downloaded
* **Filter:** Downloaded only / All
* **Read offline:** Opens in same MangaViewer (local files)
* **Storage:** `<userData>/downloads/manga/<namespace>/<sourceId>/<chapterKey>/`

### Cleanup

* Auto-delete read chapters (configurable)
* Max storage limit (Settings → Advanced → Disk Allocation)
* Manual delete per chapter/volume/series

***

## Settings (Settings → Manga)

| Category       | Options                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| **Reading**    | Default mode (vertical/paged/spread), RTL default, auto-advance chapter |
| **Appearance** | Background color, page gap, spread gap, fit width default               |
| **Navigation** | Swipe sensitivity, long-press actions, double-tap zoom                  |
| **Progress**   | Auto-mark chapter read (%), sync frequency, show progress badges        |
| **Downloads**  | Quality (original/compressed), auto-download next, WiFi only            |
| **Sources**    | Preferred language order, preferred scanlator, hide duplicates          |

***

## Extension Integration

### Adding a Manga Source

{% stepper %}
{% step %}

## Declare manga capability

Extension declares `capabilities: ["manga"]`.
{% endstep %}

{% step %}

## Implement manga methods

Implements `getMangaChapters` + `getMangaPages`.
{% endstep %}

{% step %}

## Auto-discovery

Host auto-discovers via `electron.listInstalledExtensions`.
{% endstep %}

{% step %}

## Chapter list availability

Appears in chapter list automatically.
{% endstep %}
{% endstepper %}

### Custom Source (`kind=read`)

```json
{
  "customSources": [{
    "id": "mywebtoon",
    "name": "My Webtoon",
    "kind": "read",
    "language": "ko"
  }]
}
```

* Renders in generic MangaReader at `/x/<ns>/mywebtoon/read/...`
* Progress isolated from main manga readlist

***

## Performance

| Optimization         | Implementation                             |
| -------------------- | ------------------------------------------ |
| **Virtualized list** | `@tanstack/react-virtual` for chapter list |
| **Image preload**    | Next 3 pages preloaded in background       |
| **Canvas rendering** | Optional canvas for smooth zoom/pan        |
| **Cache**            | Chapter lists cached 30 min (host)         |
| **Proxy tokens**     | Re-minted per request (15 min TTL)         |

***

## Accessibility

* **Screen reader:** Chapter list announced, page changes announced
* **Keyboard:** Full navigation without mouse
* **High contrast:** Theme respects OS high contrast
* **Reduced motion:** Disables page turn animations
* **Font scaling:** Respects system font size

***

## Related

* [Video Player](/feature-guides/video-player.md)
* [Novel Reader](/feature-guides/novel-reader.md)
* [Downloads](/feature-guides/downloads-and-offline-access.md)
* [Extension Manga Capability](/extensions/extension-capabilities/manga-capability.md)
* [Custom Source](/extensions/extension-capabilities/custom-sources.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tatakai.me/feature-guides/manga-reader.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.