kitepdf-core/io.github.yuroyami.kitepdf.core

Package-level declarations

Types

class ByteArrayBuilder(initialCapacity: Int = 64)

Grow-on-demand byte buffer. Pure Kotlin (no platform OutputStream classes), so it works in commonMain across all targets, and it's faster than mutableListOf<Byte>() because it stores into a contiguous primitive array.

ByteReader

class ByteReader(val bytes: ByteArray)

Random-access byte cursor over an in-memory PDF.

KiteBookmark

sealed class KiteBookmark

A reading position that survives a re-flow. Save this when the reader leaves, hand it back when they return, and they land where they were even if the font size, page size or margins changed in between.

KiteByteSource

interface KiteByteSource

Bytes that a reader can fetch at any offset, such as a file on disk.

KiteCancellation

fun interface KiteCancellation

A signal that a render in progress may stop early, as MuPDF's abort cookie does. A renderer checks it between operators. Once it reads true, the render paints nothing more and returns promptly, with the canvas closed (#188).

KiteCaret

class KiteCaret(val position: Double, val inside: Double, val from: Double, val to: Double, val vertical: Boolean)

A caret at a char boundary, in display space. position is where it sits along its line: x on a horizontal line, y in a vertical one. It spans the line from from to to across it. inside is the other edge of the char the caret belongs to, so it gives the direction into that char.

KiteDataUrl

class KiteDataUrl

The content of a data: URL (RFC 2397): its media type and its bytes. A document carries a small resource inside itself this way, an image or a font as Base64, or an SVG percent-encoded:

KiteDocument

interface KiteDocument

A parsed document from any handler: the fz_document equivalent. Lets a viewer treat a io.github.yuroyami.kitepdf.PdfDocument and an io.github.yuroyami.kitepdf.epub.EpubDocument uniformly.

KiteFormatException

open class KiteFormatException(message: String, cause: Throwable? = null) : RuntimeException

Common supertype for "these bytes are not a well-formed document of the format this handler reads" failures. Format handlers throw a subtype (PdfFormatException, EpubFormatException, ...) with a precise message; callers that prefer null-on-failure use the handler's openOrNull.

KiteLineEnd

enum class KiteLineEnd : Enum<KiteLineEnd>

How a KiteTextLine ends, which decides how KiteStructuredText.copyText joins it to the next line of its block.

KiteLink

class KiteLink(val rect: KiteRectangle, val uri: String? = null, val target: KiteBookmark? = null, targetY: () -> Double?? = null)

A link on a page: the area that a tap follows, and where the link leads (#433).

KiteLinkKind

enum class KiteLinkKind : Enum<KiteLinkKind>

What a link is for. A viewer can open a reference in place, such as a note in a popup, instead of moving the reader away from the page.

KiteLocation

data class KiteLocation(val chapter: Int, val page: Int) : Comparable<KiteLocation>

Where a page sits in the CURRENT layout: chapter, then page inside it.

KiteLock

expect class KiteLock

A minimal reentrant mutual-exclusion lock. JVM/Android wrap ReentrantLock, native targets a reentrant atomic spinlock, JS/Wasm are single-threaded no-ops. Use through withLock.

KiteMetadata

data class KiteMetadata(val title: String? = null, val authors: List<String> = emptyList(), val language: String? = null, val rightToLeft: Boolean = false)

Format-neutral document metadata, for a viewer's title bar / info panel. PDF fills it from /Info and XMP; EPUB from the OPF dc: elements.

KiteOutlineItem

class KiteOutlineItem(val title: String, val pageIndex: Int?, val children: List<KiteOutlineItem> = emptyList(), val target: KiteBookmark? = null)

One node of a format-neutral outline (PDF bookmarks / EPUB table of contents), for a viewer's navigation panel.

KitePage

interface KitePage

A renderable page from any document handler: the format-neutral fz_page equivalent. Both io.github.yuroyami.kitepdf.PdfPage and io.github.yuroyami.kitepdf.epub.EpubPage implement it, so one viewer / rasterizer path serves every format.

KiteRawApi

@RequiresOptIn(message = "Raw PDF object-model API: stable file format, unstable Kotlin surface. May change between minor releases.", level = RequiresOptIn.Level.WARNING)

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.CONSTRUCTOR])

annotation class KiteRawApi

Marks the raw object-model surface: direct access to xref tables, trailer dictionaries, indirect-object resolution, and the low-level editor primitives. The FILE FORMAT these expose is stable; the Kotlin surface is not, and may change between minor releases without a deprecation cycle. High-level API (pages, outlines, form fields, rendering, search) never requires this opt-in.

KiteReadingItem

class KiteReadingItem(val role: KiteRole, val text: String, val headingLevel: Int = 0, val sourceType: String? = null, val pronunciation: String? = null, val alphabet: String? = null, val language: String? = null, val bounds: KiteRectangle? = null)

One stop in a page's reading order: what a screen reader would announce, in the order it would announce it. KitePage.readingOrder gives the items of a page of any format.

KiteRectangle

data class KiteRectangle(val left: Double, val bottom: Double, val right: Double, val top: Double)

PDF rectangle: left, bottom, right, top in user-space units.

KiteRole

enum class KiteRole : Enum<KiteRole>

What a piece of content is, for a reader that speaks rather than draws. It comes from the structure of the source, not from how the content looks: an EPUB <h2> or a tagged PDF /H2 is a heading whatever its style, and a large bold paragraph is not.

KiteSearchHit

class KiteSearchHit(val pageIndex: Int, val quads: List<KiteRectangle>, val text: String, val location: KiteLocation?)

One search match: display-space quads (one per line touched) at location. The location is a coordinate in the current layout, so it and the quads must be recomputed when that layout changes. It is not a reflow-stable content anchor.

KiteStructuredText

class KiteStructuredText(val blocks: List<KiteTextBlock>)

Format-neutral structured text for a KitePage: the minimal blocks → lines → text model a viewer needs for extraction, search highlights and selection, without committing to a handler's internals.

KiteTextBlock

class KiteTextBlock(val lines: List<KiteTextLine>)

A paragraph-ish group of consecutive lines from one layout block.

KiteTextLine

class KiteTextLine(val text: String, val bounds: KiteRectangle, val charEdges: DoubleArray, val vertical: Boolean = false, val end: KiteLineEnd = KiteLineEnd.HARD)

One laid-out line. charEdges has text.length + 1 display-space boundaries: charEdges[i] is where char i starts, the final entry where the line ends. That is enough to build sub-line highlight quads. Entries follow the text's logical order, so right-to-left runs may have descending edges and positioned runs may change direction. Hit tests use each adjacent pair's extent; highlights enclose every selected pair.

KiteWarnings

object KiteWarnings

The fz_warn equivalent: a process-global, nullable warning sink for the places where the engine silently salvages (cached-null resolves, repair fallbacks, skipped page-tree kids, failed filters, placeholder images).

KiteWarningSink

fun interface KiteWarningSink

Receives one-line diagnostics from lenient salvage paths.

KiteWrongPasswordException

class KiteWrongPasswordException(message: String, cause: Throwable? = null) : RuntimeException

Raised when a document is encrypted and the supplied password did not authenticate. PDF standard security raises it today; the type is format-neutral so a future DRM-aware handler can raise the same one.

PdfFormatException

class PdfFormatException(message: String, cause: Throwable? = null) : KiteFormatException

Raised for any structural PDF error: bad header, truncated stream, malformed xref, etc.

Rectangle

typealias ~~Rectangle~~ = KiteRectangle

WrongPasswordException

typealias ~~WrongPasswordException~~ = KiteWrongPasswordException

Functions

currentThreadId

expect fun currentThreadId(): Long

A stable identifier for the calling thread (0 on single-threaded targets). Lets cycle guards distinguish same-thread reentrancy (a real cycle) from another thread legitimately resolving the same object concurrently.

kiteWarn

fun kiteWarn(message: () -> String)

Emit through KiteWarnings.sink. Message construction is lazy (free when no sink is installed) and a throwing sink can never break the caller.

withLock

inline fun <T> KiteLock.withLock(block: () -> T): T