yom-format 0.1.0

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * Public API for reading, writing, and validating YOM v1 packfiles.
+ *
+ * This entry point is platform-agnostic (no DOM/pdf.js dependency). For the
+ * browser-only PDF-to-YOM conversion pipeline, import from
+ * `yom-format/pipeline` instead.
+ */
+
+export { YOMPackfileReader, YOMReaderError } from "./yom/reader.js";
+
+export {
+  type ByteSource,
+  MemoryByteSource,
+  HttpRangeByteSource,
+  ByteSourceError,
+  type HttpRangeOptions,
+} from "./yom/byteSource.js";
+
+export {
+  YOMError,
+  BlobTooLargeError,
+  CorruptBlobError,
+  MalformedIndexError,
+  RangeNotSupportedError,
+} from "./yom/errors.js";
+
+export { verifyMainIndex } from "./yom/flatbufferVerify.js";
+
+export {
+  MAX_BLOB_UNCOMPRESSED_IMAGE,
+  MAX_BLOB_UNCOMPRESSED_TEXT,
+  MAX_BLOB_UNCOMPRESSED_POSTINGS,
+  MAX_TOTAL_UNCOMPRESSED,
+  MAX_INFLATION_RATIO,
+  maxBlobUncompressed,
+} from "./yom/constants.js";
+
+export {
+  writeYOM,
+  YOMWriterError,
+  type WriterInput,
+  type BookInput,
+  type PageInput,
+  type BlobInput,
+  type SearchTermInput,
+  type OutlineInput,
+  type PDFExportInput,
+} from "./yom/writer.js";
+
+export { validateYOM, YOMValidationError } from "./yom/validator.js";
+
+export {
+  YOM_FILE_EXTENSION,
+  YOM_MIME_TYPE,
+  YOM_MAGIC,
+  YOM_HEADER_SIZE,
+  YOM_FORMAT_VERSION,
+  YOM_HASH_LENGTH,
+  YOM_IMAGE_BLOB_ALIGNMENT,
+  YOM_DEFAULT_BLOB_ALIGNMENT,
+  requiredCompression,
+  requiredAlignment,
+} from "./yom/constants.js";
+
+export {
+  HEADER_FIELDS_SIZE,
+  type YOMHeader,
+  YOMHeaderParseError,
+  encodeHeaderFields,
+  encodeHeader,
+  encodeFooter,
+  parseHeaderFields,
+  zeroingHashes,
+  headersEqual,
+} from "./yom/header.js";
+
+export {
+  buildSearchIndex,
+  decodePostings,
+  type SearchTerm,
+  type SearchIndexResult,
+  type Hit,
+} from "./yom/searchIndex.js";
+
+export {
+  normalizeText,
+  buildNormalizedTextBlob,
+  type NormalizedTextBlob,
+} from "./yom/textNormalizer.js";
+
+export { sha256, bytesEqual } from "./yom/hash.js";
+export { concatBytes } from "./yom/bytes.js";
+
+// FlatBuffers-generated enums and record types used by the API above.
+export { BlobKind } from "./yom/generated/yomu/yom/blob-kind.js";
+export { Compression } from "./yom/generated/yomu/yom/compression.js";
+export { ReadingDirection } from "./yom/generated/yomu/yom/reading-direction.js";
+export type { MainIndex } from "./yom/generated/yomu/yom/main-index.js";
+export type { PageEntry } from "./yom/generated/yomu/yom/page-entry.js";
+export type { BlobRef } from "./yom/generated/yomu/yom/blob-ref.js";
+export type { BookMetadata } from "./yom/generated/yomu/yom/book-metadata.js";
+export type { OutlineEntry } from "./yom/generated/yomu/yom/outline-entry.js";
+export type { SearchTermRef } from "./yom/generated/yomu/yom/search-term-ref.js";
+export type { PDFExportMetadata } from "./yom/generated/yomu/yom/pdfexport-metadata.js";
+export type { OCRLayout } from "./yom/generated/yomu/yom/ocrlayout.js";
+export type { OCRPage } from "./yom/generated/yomu/yom/ocrpage.js";
+export type { OCRBlock } from "./yom/generated/yomu/yom/ocrblock.js";
+export type { OCRLine } from "./yom/generated/yomu/yom/ocrline.js";
+export type { OCRToken } from "./yom/generated/yomu/yom/ocrtoken.js";

package/src/pipeline/avif.ts

@@ -0,0 +1,33 @@
+import encode from "@jsquash/avif/encode";
+
+/**
+ * AVIF is the only page/thumbnail image codec YOM v1 supports (see
+ * docs/format-spec.md §5.1-5.2). `@jsquash/avif`'s `quality` is a 0-100
+ * cq-level scale, independent of the
+ * native encoder's ImageIO `0..1` quality knob (`AVIFCodec.swift`) -- these
+ * two encoders are not required to numerically match, only to both emit
+ * valid, reasonably-sized AVIF per the format's page/thumbnail split.
+ */
+const PAGE_QUALITY = 60;
+const THUMBNAIL_QUALITY = 40;
+
+/**
+ * libavif's `speed` is 0 (slowest/best compression) to 10 (fastest/worst
+ * compression); `@jsquash/avif`'s default is 6 ("balanced"). This app's own
+ * product direction is an "extremely fast, focused" reader over archival
+ * image quality (see `pivot-fast-reader-remove-ai-ocr`), and these pages are
+ * themselves lossy re-renders of the source PDF rather than original scans,
+ * so trading a little compression efficiency for much faster encoding is
+ * the right default for a browser-only, no-hardware-encoder pipeline.
+ */
+const ENCODE_SPEED = 9;
+
+export async function encodePageAvif(image: ImageData): Promise<Uint8Array> {
+  const buffer = await encode(image, { quality: PAGE_QUALITY, speed: ENCODE_SPEED });
+  return new Uint8Array(buffer);
+}
+
+export async function encodeThumbnailAvif(image: ImageData): Promise<Uint8Array> {
+  const buffer = await encode(image, { quality: THUMBNAIL_QUALITY, speed: ENCODE_SPEED });
+  return new Uint8Array(buffer);
+}

package/src/pipeline/convert.ts

@@ -0,0 +1,148 @@
+import { BlobKind } from "../yom/generated/yomu/yom/blob-kind.js";
+import { Compression } from "../yom/generated/yomu/yom/compression.js";
+import { ReadingDirection } from "../yom/generated/yomu/yom/reading-direction.js";
+import { writeYOM, type WriterInput, type SearchTermInput } from "../yom/writer.js";
+import { validateYOM } from "../yom/validator.js";
+import { buildNormalizedTextBlob } from "../yom/textNormalizer.js";
+import { buildSearchIndex } from "../yom/searchIndex.js";
+import { loadPdfDocument, extractOutline, extractPageLabels } from "./pdfDocument.js";
+import { renderPage } from "./renderPage.js";
+import { extractPageText, type PageText } from "./textExtract.js";
+import { encodePageAvif, encodeThumbnailAvif } from "./avif.js";
+import { buildOcrLayoutBlob } from "./ocrLayoutBuilder.js";
+
+/**
+ * Mirrors the Swift implementation's `YOMConverter.Stage`
+ * (`swift/Sources/YOMConverter/YOMConverter.swift`) so Web and native
+ * progress reporting read the same way. `rendering`, `encoding`, and
+ * `extractingText` all advance together per-page here since this pipeline
+ * does all three in one pass per page (see `convertPdfToYom`).
+ */
+export type ConversionStage =
+  | "rendering"
+  | "encoding"
+  | "extractingText"
+  | "buildingSearchIndex"
+  | "writingPackfile"
+  | "validating";
+
+export type ProgressCallback = (stage: ConversionStage, fraction: number) => void;
+
+export class ConversionCancelledError extends Error {
+  constructor() {
+    super("conversion cancelled");
+  }
+}
+
+export interface ConvertOptions {
+  title: string;
+  onProgress?: ProgressCallback;
+  isCancelled?: () => boolean;
+}
+
+/**
+ * Converts a source PDF's bytes into a validated `.yom` package, entirely in
+ * the browser. Ports the shape of the Swift implementation's
+ * `YOMConverter.convert` + `YOMConversionPipeline.buildWriterInput`
+ * (`swift/Sources/YOMConverter/`), with two known scope differences:
+ * image-only pages get no OCR text yet (a vendored OCR engine for that is
+ * not yet implemented), and PDF export metadata is generated but not
+ * consumed by an export feature yet.
+ */
+export async function convertPdfToYom(pdfBytes: Uint8Array, options: ConvertOptions): Promise<Uint8Array> {
+  const { title, onProgress = () => {}, isCancelled = () => false } = options;
+
+  const doc = await loadPdfDocument(pdfBytes);
+  const pageCount = doc.numPages;
+  if (pageCount === 0) throw new Error("PDF has no pages");
+
+  const [outline, pageLabels] = await Promise.all([extractOutline(doc), extractPageLabels(doc)]);
+
+  const pageTexts: PageText[] = [];
+  const pageInputs: WriterInput["pages"] = [];
+
+  for (let i = 0; i < pageCount; i++) {
+    if (isCancelled()) throw new ConversionCancelledError();
+
+    const page = await doc.getPage(i + 1);
+    const rendered = await renderPage(page);
+    onProgress("rendering", (i + 1) / pageCount);
+
+    const [pageAvif, thumbAvif] = await Promise.all([
+      encodePageAvif(rendered.image),
+      encodeThumbnailAvif(rendered.thumbnail),
+    ]);
+    onProgress("encoding", (i + 1) / pageCount);
+
+    const pageText = await extractPageText(page, rendered.viewport);
+    pageTexts.push(pageText);
+    onProgress("extractingText", (i + 1) / pageCount);
+
+    // Geometry uses PDF-space `page.view` (pdf.js does not expose distinct
+    // mediaBox/cropBox), matching the native converter's own simplification
+    // of collapsing contentBox into cropBox (`YOMPDFExportMetadata.swift`).
+    const pdfBox = page.view.slice();
+
+    pageInputs.push({
+      pageLabel: pageLabels[i] ?? `${i + 1}`,
+      pixelWidth: rendered.image.width,
+      pixelHeight: rendered.image.height,
+      dpi: 150,
+      colorSpace: "sRGB",
+      colorProfileRef: "",
+      mediaBox: pdfBox,
+      cropBox: pdfBox,
+      contentBox: pdfBox,
+      rotation: page.rotate,
+      readingDirection: ReadingDirection.LeftToRight,
+      pageImage: { kind: BlobKind.PageImage, data: pageAvif, compression: Compression.None },
+      thumbnail: { kind: BlobKind.ThumbnailImage, data: thumbAvif, compression: Compression.None },
+    });
+
+    page.cleanup();
+  }
+
+  if (isCancelled()) throw new ConversionCancelledError();
+
+  onProgress("buildingSearchIndex", 0);
+  const ocrLayoutBytes = buildOcrLayoutBlob(pageTexts);
+  const normalized = buildNormalizedTextBlob(pageTexts.map((p) => p.text));
+  const searchIndex = buildSearchIndex(normalized.normalizedPageTexts);
+  const searchTerms: SearchTermInput[] = searchIndex.searchTerms.map((t) => ({
+    term: t.term,
+    dictionaryOffset: BigInt(t.dictionaryOffset),
+    dictionaryLength: BigInt(t.dictionaryLength),
+    postingsOffset: BigInt(t.postingsOffset),
+    postingsLength: BigInt(t.postingsLength),
+  }));
+  onProgress("buildingSearchIndex", 1);
+
+  const writerInput: WriterInput = {
+    book: {
+      title,
+      readingDirection: ReadingDirection.LeftToRight,
+      createdAtUnix: BigInt(Math.floor(Date.now() / 1000)),
+    },
+    pages: pageInputs,
+    ocrLayout: { kind: BlobKind.OCRLayout, data: ocrLayoutBytes, compression: Compression.Zstd },
+    normalizedText: { kind: BlobKind.NormalizedText, data: normalized.data, compression: Compression.Zstd },
+    searchDictionary: { kind: BlobKind.SearchDictionary, data: searchIndex.dictionaryBlob, compression: Compression.Zstd },
+    searchPostings: { kind: BlobKind.SearchPostings, data: searchIndex.postingsBlob, compression: Compression.None },
+    searchTerms,
+    pdfExport: { pageLabels, outline },
+  };
+
+  if (isCancelled()) throw new ConversionCancelledError();
+
+  onProgress("writingPackfile", 0);
+  const packfileBytes = await writeYOM(writerInput);
+  onProgress("writingPackfile", 1);
+
+  if (isCancelled()) throw new ConversionCancelledError();
+
+  onProgress("validating", 0);
+  await validateYOM(packfileBytes);
+  onProgress("validating", 1);
+
+  return packfileBytes;
+}

package/src/pipeline/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Browser-only PDF-to-YOM conversion pipeline: renders a PDF with pdf.js,
+ * encodes pages/thumbnails as AVIF, extracts embedded text and outline, and
+ * writes a validated `.yom` package. Requires a DOM (Canvas/OffscreenCanvas)
+ * environment; it will not run under plain Node.
+ *
+ * Kept as a separate subpath (`yom-format/pipeline`) so the core read/write
+ * API in `yom-format` stays free of the pdf.js and image-codec dependencies
+ * this pulls in.
+ */
+
+export {
+  convertPdfToYom,
+  ConversionCancelledError,
+  type ConversionStage,
+  type ProgressCallback,
+  type ConvertOptions,
+} from "./convert.js";
+
+export { loadPdfDocument, extractOutline, extractPageLabels, type OutlineEntryData } from "./pdfDocument.js";
+
+export { renderPage, THUMBNAIL_MAX_DIMENSION, type RenderedPage } from "./renderPage.js";
+
+export { extractPageText, type PageText, type PageTextToken } from "./textExtract.js";
+
+export { encodePageAvif, encodeThumbnailAvif } from "./avif.js";
+
+export { buildOcrLayoutBlob } from "./ocrLayoutBuilder.js";

package/src/pipeline/ocrLayoutBuilder.ts

@@ -0,0 +1,73 @@
+import { Builder } from "flatbuffers";
+import { OCRLayoutT } from "../yom/generated/yomu/yom/ocrlayout.js";
+import { OCRPageT } from "../yom/generated/yomu/yom/ocrpage.js";
+import { OCRBlockT } from "../yom/generated/yomu/yom/ocrblock.js";
+import { OCRLineT } from "../yom/generated/yomu/yom/ocrline.js";
+import { OCRTokenT } from "../yom/generated/yomu/yom/ocrtoken.js";
+import { concatBytes } from "../yom/bytes.js";
+import type { PageText, PageTextToken } from "./textExtract.js";
+
+type Bbox = [number, number, number, number];
+
+/**
+ * Builds the pre-compression OCR FlatBuffers blob (`writer.ts` zstd-
+ * compresses it per the fixed policy) from per-page token layout. Each
+ * page's `text` field is the concatenation of its own tokens' text, in
+ * order, with no separators -- `textStart`/`textLength` index directly into
+ * that buffer, not into the original PDF text run structure.
+ */
+export function buildOcrLayoutBlob(pages: PageText[]): Uint8Array {
+  const encoder = new TextEncoder();
+  const builder = new Builder(1024);
+  builder.forceDefaults(true);
+
+  const ocrPages = pages.map((page, pageIndex) => {
+    const tokenBytesList = page.tokens.map((t) => encoder.encode(t.text));
+    let cursor = 0;
+    const tokens = page.tokens.map((token, i) => {
+      const bytes = tokenBytesList[i];
+      const textStart = cursor;
+      cursor += bytes.length;
+      return new OCRTokenT(textStart, bytes.length, token.bbox, 1.0, token.lineId, token.blockId);
+    });
+
+    const pageText = new TextDecoder().decode(concatBytes(tokenBytesList));
+
+    const lineBboxes = new Map<number, Bbox>();
+    const blockBboxes = new Map<number, Bbox>();
+    for (const token of page.tokens) {
+      unionBbox(lineBboxes, token.lineId, token.bbox);
+      unionBbox(blockBboxes, token.blockId, token.bbox);
+    }
+
+    const lines = Array.from(lineBboxes.keys())
+      .sort((a, b) => a - b)
+      .map((id) => new OCRLineT(id, blockIdForLine(page.tokens, id), lineBboxes.get(id)!));
+    const blocks = Array.from(blockBboxes.keys())
+      .sort((a, b) => a - b)
+      .map((id) => new OCRBlockT(id, blockBboxes.get(id)!));
+
+    return new OCRPageT(pageIndex, pageText, blocks, lines, tokens);
+  });
+
+  const layout = new OCRLayoutT(ocrPages);
+  const offset = layout.pack(builder);
+  builder.finish(offset);
+  return builder.asUint8Array();
+}
+
+function blockIdForLine(tokens: PageTextToken[], lineId: number): number {
+  return tokens.find((t) => t.lineId === lineId)?.blockId ?? 0;
+}
+
+function unionBbox(map: Map<number, Bbox>, id: number, bbox: Bbox): void {
+  const existing = map.get(id);
+  if (!existing) {
+    map.set(id, [...bbox]);
+    return;
+  }
+  existing[0] = Math.min(existing[0], bbox[0]);
+  existing[1] = Math.min(existing[1], bbox[1]);
+  existing[2] = Math.max(existing[2], bbox[2]);
+  existing[3] = Math.max(existing[3], bbox[3]);
+}

package/src/pipeline/pdfDocument.ts

@@ -0,0 +1,86 @@
+import { GlobalWorkerOptions, getDocument } from "pdfjs-dist";
+import type { PDFDocumentProxy } from "pdfjs-dist";
+
+// Runs inside `convert.worker.ts`; pdf.js spawns (or fakes, if the browser
+// disallows a nested worker) its own core worker from this URL.
+GlobalWorkerOptions.workerSrc = new URL("pdfjs-dist/build/pdf.worker.mjs", import.meta.url).href;
+
+/**
+ * Minimal `CanvasFactory` so pdf.js's *internal* auxiliary canvases (soft
+ * masks, tiling patterns) work in a Worker, where `document` does not exist.
+ * Our own top-level per-page render target is a separate `OffscreenCanvas`
+ * created directly in `renderPage.ts`.
+ */
+class OffscreenCanvasFactory {
+  create(width: number, height: number) {
+    const canvas = new OffscreenCanvas(width, height);
+    const context = canvas.getContext("2d");
+    return { canvas, context };
+  }
+  reset(canvasAndContext: { canvas: OffscreenCanvas }, width: number, height: number) {
+    canvasAndContext.canvas.width = width;
+    canvasAndContext.canvas.height = height;
+  }
+  destroy(canvasAndContext: { canvas: OffscreenCanvas | null; context: unknown }) {
+    canvasAndContext.canvas = null;
+    canvasAndContext.context = null;
+  }
+}
+
+export async function loadPdfDocument(data: Uint8Array): Promise<PDFDocumentProxy> {
+  // pdf.js instantiates this itself (`new CanvasFactory(...)`), so the
+  // option must be the class, not an instance of it.
+  const task = getDocument({ data, CanvasFactory: OffscreenCanvasFactory as unknown as never });
+  return task.promise;
+}
+
+export interface OutlineEntryData {
+  title: string;
+  pageId: number;
+  children: OutlineEntryData[];
+}
+
+/** Extracts the PDF outline/TOC, resolving each destination to a page index. */
+export async function extractOutline(doc: PDFDocumentProxy): Promise<OutlineEntryData[]> {
+  const raw = await doc.getOutline();
+  if (!raw) return [];
+  return resolveOutlineNodes(doc, raw);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function resolveOutlineNodes(doc: PDFDocumentProxy, nodes: any[]): Promise<OutlineEntryData[]> {
+  const result: OutlineEntryData[] = [];
+  for (const node of nodes) {
+    const pageId = await resolvePageId(doc, node.dest);
+    const children = node.items?.length ? await resolveOutlineNodes(doc, node.items) : [];
+    result.push({ title: typeof node.title === "string" ? node.title : "", pageId, children });
+  }
+  return result;
+}
+
+async function resolvePageId(
+  doc: PDFDocumentProxy,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dest: string | any[] | null | undefined,
+): Promise<number> {
+  try {
+    let resolved = dest;
+    if (typeof resolved === "string") {
+      resolved = await doc.getDestination(resolved);
+    }
+    if (!Array.isArray(resolved) || resolved.length === 0) return 0;
+    const ref = resolved[0];
+    if (typeof ref === "number") return ref;
+    const index = await doc.getPageIndex(ref);
+    return index >= 0 ? index : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Page labels, falling back to 1-based numbering when the PDF has none. */
+export async function extractPageLabels(doc: PDFDocumentProxy): Promise<string[]> {
+  const labels = await doc.getPageLabels();
+  if (labels) return labels;
+  return Array.from({ length: doc.numPages }, (_, i) => `${i + 1}`);
+}

package/src/pipeline/renderPage.ts

@@ -0,0 +1,48 @@
+import type { PDFPageProxy } from "pdfjs-dist";
+import type { PageViewport } from "pdfjs-dist";
+
+/**
+ * Render resolution and thumbnail sizing. `RENDER_DPI` favors legibility for
+ * the primary reading surface (mirrors the intent behind
+ * `AVIFCodec.pageQuality` on the native side, expressed here as resolution
+ * rather than a platform-specific encoder quality knob).
+ */
+const RENDER_DPI = 150;
+export const THUMBNAIL_MAX_DIMENSION = 320;
+
+export interface RenderedPage {
+  image: ImageData;
+  thumbnail: ImageData;
+  viewport: PageViewport;
+}
+
+export async function renderPage(page: PDFPageProxy): Promise<RenderedPage> {
+  const scale = RENDER_DPI / 72;
+  const viewport = page.getViewport({ scale });
+  const width = Math.max(1, Math.round(viewport.width));
+  const height = Math.max(1, Math.round(viewport.height));
+
+  const canvas = new OffscreenCanvas(width, height);
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("failed to acquire 2D rendering context");
+
+  await page.render({
+    canvas: null,
+    canvasContext: ctx as unknown as CanvasRenderingContext2D,
+    viewport,
+  }).promise;
+  const image = ctx.getImageData(0, 0, width, height);
+
+  const longestSide = Math.max(width, height);
+  const thumbScale = longestSide > THUMBNAIL_MAX_DIMENSION ? THUMBNAIL_MAX_DIMENSION / longestSide : 1;
+  const thumbWidth = Math.max(1, Math.round(width * thumbScale));
+  const thumbHeight = Math.max(1, Math.round(height * thumbScale));
+
+  const thumbCanvas = new OffscreenCanvas(thumbWidth, thumbHeight);
+  const thumbCtx = thumbCanvas.getContext("2d");
+  if (!thumbCtx) throw new Error("failed to acquire 2D rendering context");
+  thumbCtx.drawImage(canvas, 0, 0, thumbWidth, thumbHeight);
+  const thumbnail = thumbCtx.getImageData(0, 0, thumbWidth, thumbHeight);
+
+  return { image, thumbnail, viewport };
+}

package/src/pipeline/textExtract.ts

@@ -0,0 +1,64 @@
+import type { PDFPageProxy, PageViewport } from "pdfjs-dist";
+
+export interface PageTextToken {
+  text: string;
+  /** Normalized `[x0, y0, x1, y1]`, 0..1 relative to the page. */
+  bbox: [number, number, number, number];
+  lineId: number;
+  blockId: number;
+}
+
+export interface PageText {
+  text: string;
+  tokens: PageTextToken[];
+}
+
+/**
+ * Extracts the PDF's embedded text layer as page text plus a token layout
+ * suitable for the OCR FlatBuffers schema. This is not OCR -- it reuses the
+ * PDF's own text layer positions, which is exactly the "prefer existing text
+ * layer" half of the format's OCR/text rule (see docs/format-spec.md §6,
+ * "Search/OCR quality variance"). Image-only pages (no embedded text) get an
+ * empty token list here; filling that gap with a vendored OCR engine is not
+ * yet implemented.
+ *
+ * Block/line/bbox derivation is intentionally simple (one block per page,
+ * lines split on pdf.js's `hasEOL`, an axis-aligned box approximated from
+ * each item's transform and width) since the schema only requires a valid
+ * byte range, not layout-analysis-grade precision -- true OCR is
+ * responsible for real layout quality.
+ */
+export async function extractPageText(page: PDFPageProxy, viewport: PageViewport): Promise<PageText> {
+  const content = await page.getTextContent();
+  const tokens: PageTextToken[] = [];
+  const textParts: string[] = [];
+  let lineId = 0;
+  const blockId = 0;
+
+  for (const item of content.items) {
+    if (!("str" in item)) continue; // skip TextMarkedContent entries
+    textParts.push(item.str);
+
+    if (item.str.length > 0) {
+      const [a, b, c, d, e, f] = item.transform;
+      const fontHeight = Math.hypot(c, d) || Math.hypot(a, b) || 1;
+      const x0 = e;
+      const y0 = f;
+      const x1 = e + a * item.width;
+      const y1 = f + fontHeight;
+      const [vx0, vy0] = viewport.convertToViewportPoint(x0, y0) as [number, number];
+      const [vx1, vy1] = viewport.convertToViewportPoint(x1, y1) as [number, number];
+      const bbox: [number, number, number, number] = [
+        Math.min(vx0, vx1) / viewport.width,
+        Math.min(vy0, vy1) / viewport.height,
+        Math.max(vx0, vx1) / viewport.width,
+        Math.max(vy0, vy1) / viewport.height,
+      ];
+      tokens.push({ text: item.str, bbox, lineId, blockId });
+    }
+
+    if (item.hasEOL) lineId += 1;
+  }
+
+  return { text: textParts.join(""), tokens };
+}

package/src/worker/convert.worker.ts

@@ -0,0 +1,54 @@
+import { convertPdfToYom, ConversionCancelledError, type ConversionStage } from "../pipeline/convert.js";
+
+/**
+ * Runs the whole PDF-to-YOM pipeline (pdf.js rendering via `OffscreenCanvas`,
+ * AVIF/zstd encoding, FlatBuffers writing, validation) off the main thread,
+ * so the drag-and-drop UI stays responsive during a multi-hundred-page
+ * conversion. `self` is cast to `Worker` rather than
+ * adding the `webworker` lib to `tsconfig.json`, which would conflict with
+ * the `dom` lib the rest of the app needs (both declare a global `self`).
+ */
+const ctx = self as unknown as Worker;
+
+type InboundMessage = { type: "convert"; pdfBytes: ArrayBuffer; title: string } | { type: "cancel" };
+
+type OutboundMessage =
+  | { type: "progress"; stage: ConversionStage; fraction: number }
+  | { type: "done"; bytes: ArrayBuffer }
+  | { type: "cancelled" }
+  | { type: "error"; message: string };
+
+let cancelled = false;
+
+ctx.addEventListener("message", (event: MessageEvent<InboundMessage>) => {
+  const message = event.data;
+  if (message.type === "cancel") {
+    cancelled = true;
+    return;
+  }
+  if (message.type === "convert") {
+    cancelled = false;
+    void run(message.pdfBytes, message.title);
+  }
+});
+
+function post(message: OutboundMessage, transfer: Transferable[] = []): void {
+  ctx.postMessage(message, transfer);
+}
+
+async function run(pdfBuffer: ArrayBuffer, title: string): Promise<void> {
+  try {
+    const bytes = await convertPdfToYom(new Uint8Array(pdfBuffer), {
+      title,
+      isCancelled: () => cancelled,
+      onProgress: (stage, fraction) => post({ type: "progress", stage, fraction }),
+    });
+    post({ type: "done", bytes: bytes.buffer as ArrayBuffer }, [bytes.buffer as ArrayBuffer]);
+  } catch (error) {
+    if (error instanceof ConversionCancelledError) {
+      post({ type: "cancelled" });
+      return;
+    }
+    post({ type: "error", message: error instanceof Error ? error.message : String(error) });
+  }
+}

package/src/yom/blobLimits.ts

@@ -0,0 +1,30 @@
+import type { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { MAX_INFLATION_RATIO, maxBlobUncompressed } from "./constants.js";
+import { BlobTooLargeError } from "./errors.js";
+
+/**
+ * Gap 2 reader-side size caps. Enforces, from a blob's *declared* sizes
+ * (before any bytes are read or decompressed):
+ *
+ *  - `uncompressed_length <= MAX_BLOB_UNCOMPRESSED[kind]`
+ *  - inflation ratio `uncompressed / max(compressed, 1) <= MAX_INFLATION_RATIO`
+ *
+ * so a hostile file can't drive an unbounded allocation. Offset/length
+ * against-the-source bounds are checked by the caller (reader/validator),
+ * which know the exact source extent. These are reader limits, not format
+ * requirements -- see `constants.ts`.
+ */
+export function enforceBlobSizePolicy(kind: BlobKind, compressedLength: number, uncompressedLength: number): void {
+  const cap = maxBlobUncompressed(kind);
+  if (uncompressedLength > cap) {
+    throw new BlobTooLargeError(
+      `blob kind ${kind} declares uncompressed length ${uncompressedLength} > cap ${cap}`,
+    );
+  }
+  const ratio = uncompressedLength / Math.max(compressedLength, 1);
+  if (ratio > MAX_INFLATION_RATIO) {
+    throw new BlobTooLargeError(
+      `blob kind ${kind} inflation ratio ${ratio.toFixed(1)} > cap ${MAX_INFLATION_RATIO}`,
+    );
+  }
+}