Metadata-Version: 2.4
Name: epubfix
Version: 0.2.0
Summary: Batch-fix EPUBs that fail on Kobo/Adobe RMSDK due to unsupported CSS3+ features
Project-URL: Homepage, https://github.com/RajaaKahel/epubfix
Project-URL: Repository, https://github.com/RajaaKahel/epubfix
Project-URL: Issues, https://github.com/RajaaKahel/epubfix/issues
Author: R
License-Expression: MIT
License-File: LICENSE
Keywords: css,ebook,epub,epubfix,kobo,rmsdk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: ebooklib>=0.18
Description-Content-Type: text/markdown

# epubfix

Batch-fix EPUBs that **silently fail on Kobo** (and Adobe Digital Editions) due to unsupported CSS3+.

## The Problem

Kobo e-readers use Adobe's **RMSDK** engine — a CSS parser frozen circa 2013. When your EPUB contains modern CSS (flexbox, grid, `min()`, custom properties, etc.), Kobo doesn't give you an error. It just says the file is **"corrupted"** and refuses to open it.

This happens even when your EPUB passes `epubcheck` perfectly.

See: ["Your EPUB Is Fine. Kobo Disagrees. Blame Adobe."](https://andreklein.net/your-epub-is-fine-kobo-disagrees-blame-adobe/)

## What epubfix does

Scans all CSS in an EPUB (external `.css` files, inline `<style>` blocks, `style=""` attributes) and **replaces** unsupported values with safe fallbacks:

| Broken CSS | Smart Fallback |
|------------|----------------|
| `max-width: min(150px, 30vw)` | `max-width: 150px` |
| `font-size: clamp(1rem, 2vw, 2rem)` | `font-size: 2vw` |
| `color: var(--main-color, #333)` | `color: #333` |
| `display: flex` | `display: block` |
| `display: grid` | `display: block` |
| `aspect-ratio: 2/3` | *(removed — no safe equivalent)* |

**94% of CSS retained** on real-world EPUBs while removing all RMSDK-breaking features.

## Install

```bash
pip install epubfix
```

Requires Python 3.11+ and one dependency ([ebooklib](https://github.com/aerkalov/ebooklib)).

## Usage

```bash
# Fix a single EPUB
epubfix book.epub
# Output: book_fixed.epub

# Custom output path
epubfix book.epub -o book-kobo.epub

# Batch fix all EPUBs in a folder
epubfix --batch /path/to/epubs/

# Check for issues without fixing
epubfix --check book.epub

# Verbose output
epubfix book.epub -v

# JSON output (for scripting/CI)
epubfix book.epub --json
```

## What gets fixed

| Feature | Action |
|---------|--------|
| `min()`, `max()`, `clamp()` | Replaced with safe fallback value |
| `var(--name, fallback)` | Replaced with fallback |
| `display: flex/grid` | Replaced with `display: block` |
| Flexbox/grid sub-properties | Removed |
| Modern selectors (`:is`, `:where`, `:has`) | Entire rule removed |
| Modern colors (`oklch`, `color-mix`) | Removed |
| Transitions/animations/transforms | Removed |
| `aspect-ratio`, `object-fit` | Removed or safe default |
| Custom properties (`--var`) | Removed |

Tested on the **Blitz EPUB CSS framework** (1,194 lines of modern CSS) and **W3C EPUB 3 test suite** — all RMSDK-unsafe CSS eliminated.

## How it works

1. Opens the EPUB as a ZIP archive via ebooklib
2. Finds all CSS files and inline `<style>` blocks
3. Replaces unsupported values with safe fallbacks
4. Rebuilds the EPUB with clean CSS
5. Original file is never modified

## Compared to other tools

| | epubfix | [kobofix](https://github.com/dmang-dev/kobofix) |
|---|---------|----------|
| Install | `pip install epubfix` | Single `.py` file, no deps |
| Batch mode | ✅ Built-in | ❌ |
| CSS fallbacks | Smart (preserves values) | Smart (more granular) |
| Web app | ❌ | ✅ (drag-and-drop) |
| EPUBCheck integration | ❌ | ✅ |
| `rem` → `px` | ❌ | ✅ |
| `vw/vh` → `px` | ❌ | ✅ |
| Zero dependencies | ❌ (ebooklib) | ✅ |

**Use kobofix** if you want a no-install tool with EPUBCheck integration and viewport unit conversion. **Use epubfix** if you want `pip install`, batch processing, or programmatic access.

## License

MIT
