Pages and books

getMedia(chapter, selection) returns one of three kinds of EntryMedia, and the title's type decides which Katari expects:

An exception thrown in getMedia shows as an error in the reader or player, with its message. selection only matters for video; comics and books ignore it.

A comic chapter is a list of images in reading order. Give each page its image's address when the chapter's page already has it:

override suspend fun getMedia(chapter: SEntryChapter, selection: PlaybackSelection): EntryMedia {
    val pages = fetch(baseUrl + chapter.url).select(".reader img").mapIndexed { index, image ->
        EntryImagePage(index, imageUrl = image.absUrl("src"))
    }
    return EntryMedia.ImagePages(pages)
}

Comic sources extend EntryImageHttpSource, since the reader and the downloader load images through it. When each image sits on a page of its own, give the page's address as url instead, and find the image in getImageUrl. Katari calls it only for pages without an imageUrl, when the reader nears them or the chapter is downloaded. Override imageRequest when the image host wants other headers:

override suspend fun getMedia(chapter: SEntryChapter, selection: PlaybackSelection): EntryMedia {
    val count = fetch(baseUrl + chapter.url).select(".page-select option").size
    val pages = (0 until count).map { index ->
        EntryImagePage(index, url = "$baseUrl${chapter.url}/${index + 1}")
    }
    return EntryMedia.ImagePages(pages)
}

override suspend fun getImageUrl(page: EntryImagePage): String =
    fetch(page.url).selectFirst("#page img")!!.absUrl("src")

override fun imageRequest(page: EntryImagePage, imageUrl: String): Request =
    GET(imageUrl, headers.newBuilder().set("Referer", "$baseUrl/").build())

The book reader opens two formats: a novel's chapter as HTML, and a whole book as EPUB. Which one is set by the BookContentDescriptor(format, profile, protection = "none"):

Anything else, or a protection other than none, shows as a format the reader can't open.

fun chapterMedia(chapter: SEntryChapter, html: String): EntryMedia.Book {
    val location = BookResourceLocation.InlineText(html, "text/html")
    return EntryMedia.Book(
        descriptor = BookContentDescriptor("text/html", profile = "prose-chapter"),
        catalog = BookResourceCatalog(
            resources = listOf(
                BookSourceResource(
                    id = chapter.url,
                    title = chapter.name,
                    order = 0,
                    mediaType = "text/html",
                    availability = BookResourceAvailability.AVAILABLE,
                    location = location,
                ),
            ),
            coverage = BookCatalogCoverage.COMPLETE,
        ),
        initialResourceId = chapter.url,
        initialResourceLocation = location,
        linkedResources = BookLinkedResources(
            baseUrl = baseUrl + chapter.url,
            headers = mapOf("Referer" to "$baseUrl/"),
        ),
    )
}

• The HTML is the chapter's text, cleaned of the site's menus and scripts. The reader lays it out in its own style, from the elements and styles listed below.
• For Arabic, Hebrew and other right-to-left text, put dir="rtl" and the lang on the <body>, and the reader lays the chapter out right to left.
• The chapter opens at initialResourceId, or the catalog's only resource when that is null. Its InlineText holds the whole chapter, up to the format's 4 MiB. A RemoteRequest to its address works too, and lets Katari fetch it.
• Pictures can stay as the site wrote them: an <img> whose src is a full address, an address relative to linkedResources.baseUrl (without one, to the chapter's RemoteRequest address), or a data: image. Katari fetches them with linkedResources.headers, reads their type from their bytes and keeps them in downloads. A src that is a resource's ID in the catalog names that resource instead.
• Images can be JPEG, PNG, WebP, GIF, AVIF or SVG, up to 12 MiB each and 1 MiB for SVG, and at most 32,768 pixels on a side and 64 Mi pixels in all. One that is gone shows its alt text, and the chapter still opens and downloads.
• Fonts that @font-face rules name by address, data: URI or resource ID are used too: TrueType, OpenType, WOFF or WOFF2, up to 4 MiB each.
• CSS the site applies to every chapter, such as how it draws its notes and boxes, goes in styleSheets once. Katari applies it before each chapter's own styles and keeps it with downloads.

A downloadable book is one EPUB file, fetched and opened by Katari:

fun epubMedia(chapter: SEntryChapter, epubUrl: String): EntryMedia.Book {
    val location = BookResourceLocation.RemoteRequest(epubUrl)
    return EntryMedia.Book(
        descriptor = BookContentDescriptor("application/epub+zip"),
        catalog = BookResourceCatalog(
            resources = listOf(
                BookSourceResource(
                    id = chapter.url,
                    title = chapter.name,
                    order = 0,
                    mediaType = "application/epub+zip",
                    availability = BookResourceAvailability.AVAILABLE,
                    location = location,
                ),
            ),
            coverage = BookCatalogCoverage.COMPLETE,
        ),
        initialResourceId = chapter.url,
        initialResourceLocation = location,
    )
}

The resource IDs are where Katari keeps the reader's place, so keep them the same for the same text, and give every chapter an ID of its own. The book classes are in eu.kanade.tachiyomi.source.entry, and BookContentDescriptor, BookResourceAvailability and BookCatalogCoverage in app.katari.book.api.

The reader keeps these elements and drops the tags of all others, keeping their text:

a, abbr, address, article, aside, b, blockquote, br, caption, cite, code, dd, del, details, dfn, div, dl, dt, em, figcaption, figure, footer, h1–h6, header, hr, i, img, ins, kbd, li, main, mark, nav, ol, p, pre, q, s, samp, section, small, span, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, u, ul, var.

• script, iframe, object, embed and canvas are removed with their content. audio, video and math become a note that the content isn't supported.
• Every element keeps id, role, dir, lang, xml:lang and epub:type. Besides those, a keeps href and name; img keeps src, alt, width and height; ol keeps start and type; li keeps value; td and th keep colspan, rowspan and scope; details keeps open.
• Styles come from <style> elements, style attributes and the book's styleSheets, and cascade as in a browser: tag, class, ID and attribute selectors with combinators and structural pseudo-classes such as :nth-child and :not, specificity, !important, shorthands, every colour syntax, custom properties with var(), and @media matched against the reader's page. Rules with :hover or a pseudo-element never apply, and @import and @keyframes are skipped.
• The reader draws text colour and fonts, size, weight, style, small caps, alignment including justified, indents, line height, letter spacing, case changes, decoration and text shadows. Around a passage it keeps a box with its background colour or gradient, borders, rounded corners, shadows, padding, margins and width. Flex rows and grids of more than one column sit side by side, floats let the text wrap around them, and text hidden with display: none is left out.
• Colours are fitted to the reader's theme, and users can turn a book's styles off with Publisher styles.

A chapter that goes past any of these limits fails to open as malformed:

EntryMedia.Book describes a publication as a catalog of resources, each found at a location. Most sources need only the fields in the snippets above.

A BookSourceResource has an id, and optionally a title, an order from 0, a groupId, a mediaType, which Katari otherwise reads from the bytes, a size in bytes, a revision, an availability and a location. Only resources whose availability is AVAILABLE or UNKNOWN, the default, can be read; the others, AUTHENTICATION_REQUIRED, PURCHASE_REQUIRED, REGION_RESTRICTED, REMOVED and UNSUPPORTED_APP_ACCESS, tell the user why not.

A resource's location is one of these BookResourceLocations:

LocalUri and AppReference are for Katari's own books. Every class checks its fields when created, and an invalid one, such as a blank ID, throws IllegalArgumentException from getMedia.

A site with comics and video can stay one source. Set each title's type, and make each chapter's url say what it holds, so getMedia knows which to return:

override suspend fun getMedia(chapter: SEntryChapter, selection: PlaybackSelection): EntryMedia =
    when {
        chapter.url.startsWith("/watch/") -> playback(chapter, selection)
        chapter.url.startsWith("/read/") -> pages(chapter)
        else -> error("Unknown chapter address: ${chapter.url}")
    }

When the address alone can't tell, keep the kind in the chapter's memo, a JSON object Katari stores with it and passes back.