yom-format 0.1.0

package/src/yom/textNormalizer.ts

@@ -0,0 +1,92 @@
+/**
+ * Whitespace-insensitive Japanese text normalization for YOM search. Ports
+ * the Swift implementation in `swift/Sources/YOMFormat/YOMTextNormalizer.swift`:
+ * NFKC-normalized text with all
+ * whitespace (including the full-width space U+3000) removed entirely, not
+ * just collapsed, since Japanese text carries no meaningful inter-word
+ * spacing and OCR/PDF line wraps insert whitespace at essentially arbitrary
+ * points that must not affect matching.
+ *
+ * Matches Swift's `CharacterSet.whitespacesAndNewlines` (Unicode `Zs` +
+ * newlines) rather than JS's broader `\s` (which also strips U+FEFF BOM).
+ * Every code point below is written as an explicit `\uXXXX` escape so the
+ * exact whitespace set is auditable rather than relying on invisible
+ * characters in source.
+ */
+const WHITESPACE_CODEPOINTS = [
+  0x0009, // tab
+  0x000a, // LF
+  0x000b, // vertical tab
+  0x000c, // form feed
+  0x000d, // CR
+  0x0020, // space
+  0x0085, // NEL
+  0x00a0, // no-break space (Zs)
+  0x1680, // ogham space mark (Zs)
+  0x2000,
+  0x2001,
+  0x2002,
+  0x2003,
+  0x2004,
+  0x2005,
+  0x2006,
+  0x2007,
+  0x2008,
+  0x2009,
+  0x200a, // en/em spaces etc. (Zs)
+  0x2028, // line separator
+  0x2029, // paragraph separator
+  0x202f, // narrow no-break space (Zs)
+  0x205f, // medium mathematical space (Zs)
+  0x3000, // ideographic (full-width) space (Zs)
+];
+
+const WHITESPACE_PATTERN = new RegExp(
+  `[${WHITESPACE_CODEPOINTS.map((cp) => `\\u{${cp.toString(16)}}`).join("")}]`,
+  "gu",
+);
+
+export interface NormalizedTextBlob {
+  data: Uint8Array;
+  normalizedPageTexts: string[];
+  /** Each page's byte range within `data` (end-exclusive). */
+  pageRanges: Array<{ start: number; end: number }>;
+}
+
+/** NFKC + whitespace-removal for a single page's text. */
+export function normalizeText(text: string): string {
+  return text.normalize("NFKC").replace(WHITESPACE_PATTERN, "");
+}
+
+/**
+ * Builds the single blob that stores every page's normalized text back to
+ * back, each page separated by `"\n"` (a normalized page's text never
+ * contains raw whitespace itself since it was just stripped, so `"\n"` is an
+ * unambiguous separator).
+ */
+export function buildNormalizedTextBlob(pageTexts: string[]): NormalizedTextBlob {
+  const normalizedPages = pageTexts.map(normalizeText);
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  const ranges: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+
+  for (const page of normalizedPages) {
+    const bytes = encoder.encode(page);
+    chunks.push(bytes);
+    ranges.push({ start: cursor, end: cursor + bytes.length });
+    cursor += bytes.length;
+    const newline = encoder.encode("\n");
+    chunks.push(newline);
+    cursor += newline.length;
+  }
+
+  const data = new Uint8Array(cursor);
+  let offset = 0;
+  for (const chunk of chunks) {
+    data.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  return { data, normalizedPageTexts: normalizedPages, pageRanges: ranges };
+}

package/src/yom/validator.ts

@@ -0,0 +1,245 @@
+import type { MainIndex } from "./generated/yomu/yom/main-index.js";
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.js";
+import type { BlobRef } from "./generated/yomu/yom/blob-ref.js";
+import {
+  MAX_TOTAL_UNCOMPRESSED,
+  YOM_HEADER_SIZE,
+  YOM_IMAGE_BLOB_ALIGNMENT,
+  YOM_MAGIC,
+  YOM_FORMAT_VERSION,
+  requiredCompression,
+} from "./constants.js";
+import { getVerifiedRootAsMainIndex } from "./flatbufferVerify.js";
+import { enforceBlobSizePolicy } from "./blobLimits.js";
+import { BlobTooLargeError } from "./errors.js";
+import {
+  HEADER_FIELDS_SIZE,
+  encodeFooter,
+  encodeHeader,
+  headersEqual,
+  parseHeaderFields,
+  zeroingHashes,
+  type YOMHeader,
+} from "./header.js";
+import { bytesEqual, sha256 } from "./hash.js";
+import { zstdDecompress } from "./zstd.js";
+import { concatBytes } from "./bytes.js";
+
+/**
+ * Strict, standalone validation of a YOM v1 packfile, independent of
+ * `YOMPackfileReader`. Ports the Swift implementation in
+ * `swift/Sources/YOMFormat/YOMValidator.swift`: magic/
+ * version, file-size consistency, index/file/blob hashes, blob offset bounds
+ * and alignment, the fixed compression-by-kind policy, and the "exactly one
+ * page image blob + one thumbnail blob per page" rule.
+ *
+ * Throws on the first failure found rather than collecting every violation.
+ */
+export class YOMValidationError extends Error {}
+
+export async function validateYOM(data: Uint8Array): Promise<void> {
+  const header = validateHeaderAndFooter(data);
+  const indexEnd = header.indexOffset + header.indexUncompressedLength;
+  const footerStart = data.length - HEADER_FIELDS_SIZE;
+  const indexBytes = data.subarray(Number(header.indexOffset), Number(indexEnd));
+
+  await validateIndexAndFileHashes(data, header, indexBytes, footerStart);
+
+  // Full bounded structural verification of the index before traversal (Gap 3).
+  const mainIndex = getVerifiedRootAsMainIndex(indexBytes, true);
+
+  const blobCounts = await validateBlobs(mainIndex, data, indexEnd, footerStart);
+
+  const pageCount = mainIndex.pagesLength();
+  if (blobCounts.image !== pageCount) {
+    throw new YOMValidationError(`expected ${pageCount} PageImage blobs, found ${blobCounts.image}`);
+  }
+  if (blobCounts.thumbnail !== pageCount) {
+    throw new YOMValidationError(`expected ${pageCount} ThumbnailImage blobs, found ${blobCounts.thumbnail}`);
+  }
+
+  validatePageBlobReferences(mainIndex);
+}
+
+/** Parses and cross-checks the fixed header against its footer mirror. */
+function validateHeaderAndFooter(data: Uint8Array): YOMHeader {
+  if (data.length < YOM_HEADER_SIZE + HEADER_FIELDS_SIZE) {
+    throw new YOMValidationError("file too small");
+  }
+
+  const header = parseHeaderFields(data.subarray(0, YOM_HEADER_SIZE));
+  if (!bytesEqual(header.magic, YOM_MAGIC)) throw new YOMValidationError("bad magic");
+  if (header.formatVersion !== YOM_FORMAT_VERSION) {
+    throw new YOMValidationError(`unsupported format version ${header.formatVersion}`);
+  }
+
+  const indexEnd = header.indexOffset + header.indexUncompressedLength;
+  if (header.indexOffset !== BigInt(YOM_HEADER_SIZE) || indexEnd > BigInt(data.length)) {
+    throw new YOMValidationError("index out of bounds");
+  }
+
+  const footerStart = data.length - HEADER_FIELDS_SIZE;
+  if (BigInt(footerStart) < indexEnd) throw new YOMValidationError("index out of bounds");
+  const footer = parseHeaderFields(data.subarray(footerStart));
+  if (!headersEqual(footer, header)) throw new YOMValidationError("footer does not match header");
+
+  return header;
+}
+
+/**
+ * Recomputes the index hash and the whole-file hash (with hash fields
+ * zeroed, matching the writer's convention) and compares them against the
+ * values stored in the header.
+ */
+async function validateIndexAndFileHashes(
+  data: Uint8Array,
+  header: YOMHeader,
+  indexBytes: Uint8Array,
+  footerStart: number,
+): Promise<void> {
+  const actualIndexHash = await sha256(indexBytes);
+  if (!bytesEqual(actualIndexHash, header.indexHash)) throw new YOMValidationError("index hash mismatch");
+
+  const hashingHeader = zeroingHashes(header);
+  const recomputeInput = concatBytes([
+    encodeHeader(hashingHeader),
+    data.subarray(YOM_HEADER_SIZE, footerStart),
+    encodeFooter(hashingHeader),
+  ]);
+  const actualFileHash = await sha256(recomputeInput);
+  if (!bytesEqual(actualFileHash, header.fileHash)) throw new YOMValidationError("file hash mismatch");
+}
+
+/**
+ * Validates every blob's compression policy, alignment, bounds, and hash.
+ * Returns how many PageImage/ThumbnailImage blobs were found, so the caller
+ * can enforce "exactly one of each per page, no extras".
+ */
+async function validateBlobs(
+  mainIndex: MainIndex,
+  data: Uint8Array,
+  indexEnd: bigint,
+  footerStart: number,
+): Promise<{ image: number; thumbnail: number }> {
+  let imageBlobCount = 0;
+  let thumbnailBlobCount = 0;
+  let totalUncompressed = 0;
+
+  for (let blobIndex = 0; blobIndex < mainIndex.blobsLength(); blobIndex++) {
+    const blob = mainIndex.blobs(blobIndex);
+    if (!blob) throw new YOMValidationError(`blob ${blobIndex} missing`);
+    validateBlobCompressionAndAlignment(blob, blobIndex);
+
+    const blobEnd = blob.offset() + blob.compressedLength();
+    if (blob.offset() < indexEnd || blobEnd > BigInt(footerStart)) {
+      throw new YOMValidationError(`blob ${blobIndex} out of bounds`);
+    }
+
+    // Reader-side size caps before touching bytes (Gap 2).
+    const compressedLength = Number(blob.compressedLength());
+    const uncompressedLength = Number(blob.uncompressedLength());
+    try {
+      enforceBlobSizePolicy(blob.kind(), compressedLength, uncompressedLength);
+    } catch (err) {
+      if (err instanceof BlobTooLargeError) {
+        throw new YOMValidationError(`blob ${blobIndex} ${err.message}`);
+      }
+      throw err;
+    }
+    totalUncompressed += uncompressedLength;
+    if (totalUncompressed > MAX_TOTAL_UNCOMPRESSED) {
+      throw new YOMValidationError(`total uncompressed size exceeds cap ${MAX_TOTAL_UNCOMPRESSED}`);
+    }
+
+    const rawBytes = data.subarray(Number(blob.offset()), Number(blobEnd));
+    await validateBlobHash(blob, blobIndex, uncompressedLength, rawBytes);
+
+    if (blob.kind() === BlobKind.PageImage) imageBlobCount += 1;
+    if (blob.kind() === BlobKind.ThumbnailImage) thumbnailBlobCount += 1;
+  }
+
+  return { image: imageBlobCount, thumbnail: thumbnailBlobCount };
+}
+
+function validateBlobCompressionAndAlignment(blob: BlobRef, blobIndex: number): void {
+  const required = requiredCompression(blob.kind());
+  if (blob.compression() !== required) {
+    throw new YOMValidationError(
+      `blob ${blobIndex} compression policy violation: kind ${blob.kind()} declared ${blob.compression()} required ${required}`,
+    );
+  }
+
+  const alignment = BigInt(Math.max(blob.alignment(), 1));
+  if (blob.offset() % alignment !== 0n) {
+    throw new YOMValidationError(`blob ${blobIndex} alignment violation`);
+  }
+  if (blob.kind() === BlobKind.PageImage || blob.kind() === BlobKind.ThumbnailImage) {
+    if (blob.alignment() < YOM_IMAGE_BLOB_ALIGNMENT) {
+      throw new YOMValidationError(`blob ${blobIndex} alignment violation`);
+    }
+  }
+}
+
+async function validateBlobHash(
+  blob: BlobRef,
+  blobIndex: number,
+  uncompressedLength: number,
+  rawBytes: Uint8Array,
+): Promise<void> {
+  let original: Uint8Array;
+  if (blob.compression() === Compression.None) {
+    original = rawBytes;
+  } else {
+    try {
+      original = await zstdDecompress(rawBytes, uncompressedLength);
+    } catch {
+      throw new YOMValidationError(`blob ${blobIndex} hash mismatch (decompression failed)`);
+    }
+  }
+  const actualHash = await sha256(original);
+  const expectedHash = blob.hashArray();
+  if (!expectedHash || !bytesEqual(actualHash, expectedHash)) {
+    throw new YOMValidationError(`blob ${blobIndex} hash mismatch`);
+  }
+}
+
+/**
+ * Confirms every page references exactly one PageImage and one
+ * ThumbnailImage blob, each of the right kind, with no blob shared between
+ * two pages.
+ */
+function validatePageBlobReferences(mainIndex: MainIndex): void {
+  const blobCount = mainIndex.blobsLength();
+  const usedImageBlobIndices = new Set<number>();
+  const usedThumbnailBlobIndices = new Set<number>();
+
+  for (let pageIndex = 0; pageIndex < mainIndex.pagesLength(); pageIndex++) {
+    const page = mainIndex.pages(pageIndex);
+    if (!page) throw new YOMValidationError(`page ${pageIndex} missing`);
+
+    const imageBlobIndex = page.pageImageBlobIndex();
+    if (imageBlobIndex < 0 || imageBlobIndex >= blobCount) {
+      throw new YOMValidationError(`page ${pageIndex} missing image blob`);
+    }
+    if (mainIndex.blobs(imageBlobIndex)?.kind() !== BlobKind.PageImage) {
+      throw new YOMValidationError(`page ${pageIndex} image blob has wrong kind`);
+    }
+    if (usedImageBlobIndices.has(imageBlobIndex)) {
+      throw new YOMValidationError(`blob ${imageBlobIndex} referenced as image by more than one page`);
+    }
+    usedImageBlobIndices.add(imageBlobIndex);
+
+    const thumbnailBlobIndex = page.thumbnailBlobIndex();
+    if (thumbnailBlobIndex < 0 || thumbnailBlobIndex >= blobCount) {
+      throw new YOMValidationError(`page ${pageIndex} missing thumbnail blob`);
+    }
+    if (mainIndex.blobs(thumbnailBlobIndex)?.kind() !== BlobKind.ThumbnailImage) {
+      throw new YOMValidationError(`page ${pageIndex} thumbnail blob has wrong kind`);
+    }
+    if (usedThumbnailBlobIndices.has(thumbnailBlobIndex)) {
+      throw new YOMValidationError(`blob ${thumbnailBlobIndex} referenced as thumbnail by more than one page`);
+    }
+    usedThumbnailBlobIndices.add(thumbnailBlobIndex);
+  }
+}

package/src/yom/writer.ts

@@ -0,0 +1,337 @@
+import { Builder } from "flatbuffers";
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.js";
+import type { ReadingDirection } from "./generated/yomu/yom/reading-direction.js";
+import { BlobRefT } from "./generated/yomu/yom/blob-ref.js";
+import { PageEntryT } from "./generated/yomu/yom/page-entry.js";
+import { BookMetadataT } from "./generated/yomu/yom/book-metadata.js";
+import { SearchTermRefT } from "./generated/yomu/yom/search-term-ref.js";
+import { OutlineEntryT } from "./generated/yomu/yom/outline-entry.js";
+import { PDFExportMetadataT } from "./generated/yomu/yom/pdfexport-metadata.js";
+import { MainIndexT } from "./generated/yomu/yom/main-index.js";
+import {
+  YOM_FORMAT_VERSION,
+  YOM_HASH_LENGTH,
+  YOM_HEADER_SIZE,
+  YOM_MAGIC,
+  requiredAlignment,
+  requiredCompression,
+} from "./constants.js";
+import { encodeFooter, encodeHeader, zeroingHashes, type YOMHeader } from "./header.js";
+import { sha256 } from "./hash.js";
+import { zstdCompress } from "./zstd.js";
+import { concatBytes } from "./bytes.js";
+
+/**
+ * Emits a YOM v1 packfile: `[4096-byte header][uncompressed MainIndex
+ * FlatBuffer][blob area, each blob aligned per its BlobRef.alignment,
+ * offsets relative to file start][footer mirror]`. Ports the Swift
+ * implementation in `swift/Sources/YOMFormat/YOMPackfileWriter.swift` +
+ * `YOMPackfileWriter+Index.swift` field-for-field.
+ *
+ * Compression is not caller-selectable: every blob's declared `compression`
+ * must equal `requiredCompression(kind)` exactly, checked before any bytes
+ * are written. Hashes are always computed over each blob's original
+ * (pre-compression) bytes.
+ */
+export interface BlobInput {
+  kind: BlobKind;
+  data: Uint8Array;
+  compression: Compression;
+}
+
+export interface PageInput {
+  pageLabel: string;
+  pixelWidth: number;
+  pixelHeight: number;
+  dpi: number;
+  colorSpace: string;
+  colorProfileRef: string;
+  mediaBox: number[];
+  cropBox: number[];
+  contentBox: number[];
+  rotation: number;
+  readingDirection: ReadingDirection;
+  /** Must have `kind === BlobKind.PageImage`. */
+  pageImage: BlobInput;
+  /** Must have `kind === BlobKind.ThumbnailImage`. */
+  thumbnail: BlobInput;
+}
+
+export interface BookInput {
+  title: string;
+  readingDirection: ReadingDirection;
+  createdAtUnix: bigint;
+}
+
+export interface SearchTermInput {
+  term: string;
+  dictionaryOffset: bigint;
+  dictionaryLength: bigint;
+  postingsOffset: bigint;
+  postingsLength: bigint;
+}
+
+export interface OutlineInput {
+  title: string;
+  pageId: number;
+  children: OutlineInput[];
+}
+
+export interface PDFExportInput {
+  pageLabels: string[];
+  outline: OutlineInput[];
+}
+
+export interface WriterInput {
+  book: BookInput;
+  pages: PageInput[];
+  /** Must have `kind === BlobKind.OCRLayout` when present. */
+  ocrLayout?: BlobInput;
+  /** Must have `kind === BlobKind.NormalizedText` when present. */
+  normalizedText?: BlobInput;
+  /** Must have `kind === BlobKind.SearchDictionary` when present. */
+  searchDictionary?: BlobInput;
+  /** Must have `kind === BlobKind.SearchPostings` when present. */
+  searchPostings?: BlobInput;
+  searchTerms: SearchTermInput[];
+  pdfExport?: PDFExportInput;
+}
+
+export class YOMWriterError extends Error {}
+
+/** A blob after policy validation and (if required) compression. */
+interface BlobPlan {
+  kind: BlobKind;
+  compression: Compression;
+  alignment: number;
+  storedBytes: Uint8Array;
+  uncompressedLength: bigint;
+  hash: Uint8Array;
+}
+
+async function planBlob(input: BlobInput): Promise<BlobPlan> {
+  const alignment = requiredAlignment(input.kind);
+  const uncompressedLength = BigInt(input.data.length);
+  const hash = await sha256(input.data);
+  const storedBytes = input.compression === Compression.None ? input.data : await zstdCompress(input.data);
+  return { kind: input.kind, compression: input.compression, alignment, storedBytes, uncompressedLength, hash };
+}
+
+function validatePolicy(blob: BlobInput, expectedKind: BlobKind): void {
+  if (blob.kind !== expectedKind) {
+    throw new YOMWriterError(`blob kind mismatch: expected ${expectedKind}, got ${blob.kind}`);
+  }
+  const required = requiredCompression(blob.kind);
+  if (blob.compression !== required) {
+    throw new YOMWriterError(
+      `compression policy violation for kind ${blob.kind}: declared ${blob.compression}, required ${required}`,
+    );
+  }
+}
+
+export async function writeYOM(input: WriterInput): Promise<Uint8Array> {
+  if (input.pages.length === 0) throw new YOMWriterError("YOM package must have at least one page");
+
+  const blobPlans: BlobPlan[] = [];
+  const pageBlobIndices: Array<{ image: number; thumbnail: number }> = [];
+
+  for (const page of input.pages) {
+    validatePolicy(page.pageImage, BlobKind.PageImage);
+    validatePolicy(page.thumbnail, BlobKind.ThumbnailImage);
+    const imageIndex = blobPlans.length;
+    blobPlans.push(await planBlob(page.pageImage));
+    const thumbnailIndex = blobPlans.length;
+    blobPlans.push(await planBlob(page.thumbnail));
+    pageBlobIndices.push({ image: imageIndex, thumbnail: thumbnailIndex });
+  }
+
+  let ocrIndex = -1;
+  if (input.ocrLayout) {
+    validatePolicy(input.ocrLayout, BlobKind.OCRLayout);
+    ocrIndex = blobPlans.length;
+    blobPlans.push(await planBlob(input.ocrLayout));
+  }
+  let normalizedTextIndex = -1;
+  if (input.normalizedText) {
+    validatePolicy(input.normalizedText, BlobKind.NormalizedText);
+    normalizedTextIndex = blobPlans.length;
+    blobPlans.push(await planBlob(input.normalizedText));
+  }
+  let searchDictionaryIndex = -1;
+  if (input.searchDictionary) {
+    validatePolicy(input.searchDictionary, BlobKind.SearchDictionary);
+    searchDictionaryIndex = blobPlans.length;
+    blobPlans.push(await planBlob(input.searchDictionary));
+  }
+  let searchPostingsIndex = -1;
+  if (input.searchPostings) {
+    validatePolicy(input.searchPostings, BlobKind.SearchPostings);
+    searchPostingsIndex = blobPlans.length;
+    blobPlans.push(await planBlob(input.searchPostings));
+  }
+
+  // FlatBuffers scalar fields are fixed-width, so the encoded index size does
+  // not depend on the actual blob offset *values* -- only on how many
+  // blobs/pages/strings/etc. exist. Build once with placeholder offsets to
+  // learn the index size, then again with the real offsets.
+  const placeholderOffsets = blobPlans.map(() => 0n);
+  const dryRunIndex = buildIndexBytes(
+    input,
+    blobPlans,
+    placeholderOffsets,
+    pageBlobIndices,
+    ocrIndex,
+    normalizedTextIndex,
+    searchDictionaryIndex,
+    searchPostingsIndex,
+  );
+
+  const blobAreaStart = BigInt(YOM_HEADER_SIZE) + BigInt(dryRunIndex.length);
+  const blobOffsets = computeBlobOffsets(blobPlans, blobAreaStart);
+
+  const indexBytes = buildIndexBytes(
+    input,
+    blobPlans,
+    blobOffsets,
+    pageBlobIndices,
+    ocrIndex,
+    normalizedTextIndex,
+    searchDictionaryIndex,
+    searchPostingsIndex,
+  );
+  if (indexBytes.length !== dryRunIndex.length) {
+    throw new YOMWriterError("YOM index size must not depend on blob offset values");
+  }
+
+  const bodyChunks: Uint8Array[] = [];
+  let cursor = blobAreaStart;
+  for (let i = 0; i < blobPlans.length; i++) {
+    const plan = blobPlans[i];
+    const offset = blobOffsets[i];
+    if (offset < cursor) throw new YOMWriterError("blob offsets must be monotonically increasing");
+    if (offset > cursor) {
+      bodyChunks.push(new Uint8Array(Number(offset - cursor)));
+    }
+    bodyChunks.push(plan.storedBytes);
+    cursor = offset + BigInt(plan.storedBytes.length);
+  }
+  const body = concatBytes(bodyChunks);
+
+  const indexHash = await sha256(indexBytes);
+  const header: YOMHeader = {
+    magic: YOM_MAGIC,
+    formatVersion: YOM_FORMAT_VERSION,
+    indexOffset: BigInt(YOM_HEADER_SIZE),
+    indexCompressedLength: BigInt(indexBytes.length),
+    indexUncompressedLength: BigInt(indexBytes.length),
+    indexHash,
+    fileHash: new Uint8Array(YOM_HASH_LENGTH),
+  };
+
+  // File hash is computed with both hash fields zeroed (see header.ts doc
+  // comment), then patched into the real header/footer afterwards.
+  const hashingHeader = zeroingHashes(header);
+  const fileForHashing = concatBytes([encodeHeader(hashingHeader), indexBytes, body, encodeFooter(hashingHeader)]);
+  const fileHash = await sha256(fileForHashing);
+
+  const finalHeader: YOMHeader = { ...header, fileHash };
+  return concatBytes([encodeHeader(finalHeader), indexBytes, body, encodeFooter(finalHeader)]);
+}
+
+function computeBlobOffsets(blobPlans: BlobPlan[], blobAreaStart: bigint): bigint[] {
+  const offsets: bigint[] = [];
+  let cursor = blobAreaStart;
+  for (const plan of blobPlans) {
+    const alignment = BigInt(Math.max(plan.alignment, 1));
+    const remainder = cursor % alignment;
+    if (remainder !== 0n) cursor += alignment - remainder;
+    offsets.push(cursor);
+    cursor += BigInt(plan.storedBytes.length);
+  }
+  return offsets;
+}
+
+function buildIndexBytes(
+  input: WriterInput,
+  blobPlans: BlobPlan[],
+  blobOffsets: bigint[],
+  pageBlobIndices: Array<{ image: number; thumbnail: number }>,
+  ocrIndex: number,
+  normalizedTextIndex: number,
+  searchDictionaryIndex: number,
+  searchPostingsIndex: number,
+): Uint8Array {
+  const builder = new Builder(1024);
+  // Without this, the builder omits any scalar field whose value equals its
+  // schema default (e.g. a placeholder blob offset of 0), which would make
+  // the dry-run index a different size than the real index -- breaking the
+  // "index size does not depend on blob offset values" invariant above.
+  builder.forceDefaults(true);
+
+  const pages = input.pages.map((page, index) => {
+    const { image: imageIndex, thumbnail: thumbnailIndex } = pageBlobIndices[index];
+    return new PageEntryT(
+      index,
+      page.pageLabel,
+      page.pixelWidth,
+      page.pixelHeight,
+      page.dpi,
+      page.colorSpace,
+      page.colorProfileRef,
+      page.mediaBox,
+      page.cropBox,
+      page.contentBox,
+      page.rotation,
+      page.readingDirection,
+      imageIndex,
+      thumbnailIndex,
+      Array.from(blobPlans[imageIndex].hash),
+    );
+  });
+
+  const blobs = blobPlans.map(
+    (plan, i) =>
+      new BlobRefT(
+        plan.kind,
+        blobOffsets[i],
+        BigInt(plan.storedBytes.length),
+        plan.uncompressedLength,
+        plan.compression,
+        plan.alignment,
+        Array.from(plan.hash),
+      ),
+  );
+
+  const searchTerms = input.searchTerms.map(
+    (term) =>
+      new SearchTermRefT(term.term, term.dictionaryOffset, term.dictionaryLength, term.postingsOffset, term.postingsLength),
+  );
+
+  const pdfExport = input.pdfExport
+    ? new PDFExportMetadataT(input.pdfExport.pageLabels, buildOutline(input.pdfExport.outline))
+    : null;
+
+  const book = new BookMetadataT(input.book.title, input.pages.length, input.book.readingDirection, input.book.createdAtUnix);
+
+  const mainIndex = new MainIndexT(
+    YOM_FORMAT_VERSION,
+    book,
+    pages,
+    blobs,
+    ocrIndex,
+    normalizedTextIndex,
+    searchDictionaryIndex,
+    searchPostingsIndex,
+    searchTerms,
+    pdfExport,
+  );
+
+  const offset = mainIndex.pack(builder);
+  builder.finish(offset);
+  return builder.asUint8Array();
+}
+
+function buildOutline(entries: OutlineInput[]): OutlineEntryT[] {
+  return entries.map((entry) => new OutlineEntryT(entry.title, entry.pageId, buildOutline(entry.children)));
+}