@abfcode/spine 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @abfcode/spine
+
+An in-browser EPUB parser — a TypeScript port of [Spine](https://github.com/ABFCode/Spine) (Go).
+
+Runs on `fflate` + the platform `DOMParser` (native in browsers; provide one via
+`globalThis.DOMParser` in Node, e.g. from `jsdom`). Produces structured content
+blocks, a normalized TOC, metadata, chunks, and anchor resolution — validated
+exact/near-exact against the Go implementation on a corpus of real books.
+
+## Usage
+
+```ts
+import { parse } from '@abfcode/spine'
+
+const book = parse(epubBytes) // epubBytes: Uint8Array
+book.metadata.title
+book.toc            // normalized table of contents
+book.blocks(0)      // structured blocks for spine item 0
+book.chunks({ mode: 'size', maxChars: 2000 })
+book.resolveAnchor('OEBPS/ch1.xhtml#frag')
+```
+
+In Node, set a DOMParser first:
+
+```ts
+import { JSDOM } from 'jsdom'
+globalThis.DOMParser = new JSDOM('').window.DOMParser
+```
+
+## Scripts
+
+- `npm run build` — emit `dist/` (JS + `.d.ts`)
+- `npm test` — run the vitest suite (jsdom)
+
+## Status
+
+Extracted from the Librium reader. API may still change before 1.0.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+/** In-memory EPUB archive with clean-path lookup (mirrors Go's indexZipFiles). */
+declare class Archive {
+    private byClean;
+    readonly names: string[];
+    constructor(bytes: Uint8Array);
+    private key;
+    has(p: string): boolean;
+    bytes(p: string): Uint8Array | undefined;
+    text(p: string): string | undefined;
+}
+
+interface Metadata {
+    title: string;
+    titles: MetaValue[];
+    authors: string[];
+    creators: MetaValue[];
+    contributors: MetaValue[];
+    language: string;
+    languages: string[];
+    identifiers: Identifier[];
+    publisher: string;
+    publishers: MetaValue[];
+    pubDate: string;
+    dates: MetaValue[];
+    series: string;
+    seriesIndex: string;
+    subjects: MetaValue[];
+    rights: MetaValue[];
+    descriptions: MetaValue[];
+    modified: string;
+    collections: Collection[];
+    coverHref: string;
+}
+interface CoverInfo {
+    href: string;
+    contentType: string;
+}
+interface Cover extends CoverInfo {
+    bytes: Uint8Array;
+}
+interface Identifier {
+    id: string;
+    scheme: string;
+    value: string;
+    type: string;
+}
+interface MetaValue {
+    id: string;
+    value: string;
+    language: string;
+    scheme: string;
+    fileAs: string;
+    role: string;
+    displaySeq: number;
+    refinements: Record<string, string>;
+}
+interface Collection {
+    id: string;
+    name: string;
+    type: string;
+    position: string;
+}
+interface ManifestItem {
+    id: string;
+    href: string;
+    mediaType: string;
+    properties: string[];
+    path: string;
+}
+interface SpineItem {
+    idRef: string;
+    href: string;
+    linear: boolean;
+    properties: string[];
+}
+interface TOCItem {
+    id: string;
+    label: string;
+    href: string;
+    children: TOCItem[];
+    target?: AnchorRef;
+}
+interface FlatTOCItem {
+    id: string;
+    label: string;
+    href: string;
+    depth: number;
+    parent: number;
+    target?: AnchorRef;
+}
+interface AnchorRef {
+    spineIndex: number;
+    blockIndex: number;
+    chunkId: string;
+    offset: number;
+    href: string;
+}
+interface Warning {
+    code: string;
+    message: string;
+    path: string;
+}
+type BlockKind = 'paragraph' | 'heading' | 'list_item' | 'blockquote' | 'pre' | 'hr' | 'table' | 'figure';
+type InlineKind = 'text' | 'emphasis' | 'strong' | 'link' | 'image' | 'code';
+interface Block {
+    kind: BlockKind;
+    level?: number;
+    ordered?: boolean;
+    listIndex?: number;
+    table?: Table;
+    figure?: Figure;
+    inlines?: Inline[];
+    anchors?: string[];
+}
+interface Inline {
+    kind: InlineKind;
+    text?: string;
+    href?: string;
+    src?: string;
+    alt?: string;
+    emph?: boolean;
+    strong?: boolean;
+}
+interface Table {
+    rows: TableRow[];
+}
+interface TableRow {
+    cells: TableCell[];
+}
+interface TableCell {
+    inlines: Inline[];
+    header?: boolean;
+}
+interface Figure {
+    images: Inline[];
+    caption: Inline[];
+}
+type ChunkingMode = 'paragraph' | 'size';
+interface ChunkingOptions {
+    mode: ChunkingMode;
+    maxChars: number;
+}
+interface Chunk {
+    id: string;
+    text: string;
+    href: string;
+    spineIndex: number;
+    blockIndexFrom: number;
+    blockIndexTo: number;
+    startOffset: number;
+    endOffset: number;
+    anchors: string[];
+    blocks: Block[];
+}
+
+interface FallbackPolicy {
+    scanArchive: boolean;
+    inferSpine: boolean;
+    generateTOC: boolean;
+    generateMetadata: boolean;
+}
+interface Config {
+    chunking: ChunkingOptions;
+    rootfilePath?: string;
+    fallbacks: FallbackPolicy;
+}
+declare class Book {
+    metadata: Metadata;
+    toc: TOCItem[];
+    landmarks: TOCItem[];
+    pageList: TOCItem[];
+    manifest: Map<string, ManifestItem>;
+    spine: SpineItem[];
+    warnings: Warning[];
+    anchors: Map<string, AnchorRef>;
+    rootfilePath: string;
+    basePath: string;
+    private anchorsById;
+    private archive;
+    private cfg;
+    private chunksCache;
+    private blockCache;
+    constructor(archive: Archive, cfg: Config);
+    warn(code: string, message: string, path?: string): void;
+    private cleanHref;
+    openResource(href: string): Uint8Array | undefined;
+    documentFor(href: string): Document | undefined;
+    blocks(spineIndex: number): Block[];
+    blocksByHref(href: string): Block[];
+    cover(): Cover | undefined;
+    private manifestItemByPath;
+    chunks(opts?: ChunkingOptions): Chunk[];
+    resolveAnchor(href: string): AnchorRef | undefined;
+    /** Port of deriveTOCFromHeadings — build a TOC from heading blocks. */
+    deriveTocFromHeadings(): TOCItem[];
+    /** Port of fillMissingMetadata. */
+    fillMissingMetadata(): void;
+}
+/** Port of parse.go's openWithConfig — parse an EPUB from bytes into a Book. */
+declare function parse(bytes: Uint8Array, opts?: Partial<Config>): Book;
+
+/** Port of FlattenTOC. */
+declare function flattenToc(items: TOCItem[]): FlatTOCItem[];
+
+interface TextOptions {
+    preserveLineBreaks: boolean;
+    includeHeadings: boolean;
+    headingMarkers: boolean;
+    includeListMarkers: boolean;
+    includeHorizontalRules: boolean;
+}
+/** Port of blockToText (Spine's internal text extraction). */
+declare function blockToText(block: Block, opts?: TextOptions): string;
+
+/** Go path.Clean — lexical cleanup of a slash path. */
+declare function posixClean(p: string): string;
+/** Go path.Join — join non-empty parts then Clean. */
+declare function posixJoin(...parts: string[]): string;
+/** Go path.Dir. */
+declare function posixDir(p: string): string;
+/** Port of resolvePath(base, href) — resolves an href against a base dir, keeping any #fragment. */
+declare function resolvePath(base: string, href: string): string;
+declare function contentTypeFromHref(href: string): string;
+
+export { type AnchorRef, type Block, type BlockKind, Book, type Chunk, type ChunkingMode, type ChunkingOptions, type Collection, type Config, type Cover, type CoverInfo, type FallbackPolicy, type Figure, type FlatTOCItem, type Identifier, type Inline, type InlineKind, type ManifestItem, type MetaValue, type Metadata, type SpineItem, type TOCItem, type Table, type TableCell, type TableRow, type Warning, blockToText, contentTypeFromHref, flattenToc, parse, posixClean, posixDir, posixJoin, resolvePath };