yom-format 0.1.0

package/dist/yom/writer.js

@@ -0,0 +1,154 @@
+import { Builder } from "flatbuffers";
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.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 } from "./header.js";
+import { sha256 } from "./hash.js";
+import { zstdCompress } from "./zstd.js";
+import { concatBytes } from "./bytes.js";
+export class YOMWriterError extends Error {
+}
+async function planBlob(input) {
+    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, expectedKind) {
+    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) {
+    if (input.pages.length === 0)
+        throw new YOMWriterError("YOM package must have at least one page");
+    const blobPlans = [];
+    const pageBlobIndices = [];
+    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 = [];
+    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 = {
+        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 = { ...header, fileHash };
+    return concatBytes([encodeHeader(finalHeader), indexBytes, body, encodeFooter(finalHeader)]);
+}
+function computeBlobOffsets(blobPlans, blobAreaStart) {
+    const offsets = [];
+    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, blobPlans, blobOffsets, pageBlobIndices, ocrIndex, normalizedTextIndex, searchDictionaryIndex, searchPostingsIndex) {
+    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) {
+    return entries.map((entry) => new OutlineEntryT(entry.title, entry.pageId, buildOutline(entry.children)));
+}
+//# sourceMappingURL=writer.js.map

package/dist/yom/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/yom/writer.ts"],"names":[],"mappings":"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"}

package/dist/yom/zstd.d.ts

@@ -0,0 +1,14 @@
+export declare function zstdCompress(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decompresses a zstd frame and asserts the output is exactly `expectedSize`
+ * bytes (the blob's index-declared `uncompressed_length`), converging on the
+ * Swift `ZstdCodec.decompress(_, originalSize:)` discipline.
+ *
+ * `@bokuweb/zstd-wasm`'s `decompress` takes no target-size argument (it sizes
+ * its output buffer from the frame's own declared content size), so the guard
+ * against a size-lying frame is this exact-length check plus the caller's
+ * declared-size cap (`enforceBlobSizePolicy`). A mismatch throws
+ * `CorruptBlobError` before the bytes are used, ahead of the SHA-256 gate.
+ */
+export declare function zstdDecompress(data: Uint8Array, expectedSize: number): Promise<Uint8Array>;
+//# sourceMappingURL=zstd.d.ts.map

package/dist/yom/zstd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd.d.ts","sourceRoot":"","sources":["../../src/yom/zstd.ts"],"names":[],"mappings":"AAuBA,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGxE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAOhG"}

package/dist/yom/zstd.js

@@ -0,0 +1,43 @@
+import { init, compress, decompress } from "@bokuweb/zstd-wasm";
+import { CorruptBlobError } from "./errors.js";
+/**
+ * Thin wrapper over `@bokuweb/zstd-wasm`, the Web analogue of the Swift
+ * implementation in `swift/Sources/YOMFormat/ZstdCodec.swift`'s vendored
+ * libzstd wrapper. Every YOM
+ * blob is bounded and self-describing (zstd frames carry their own content
+ * size), so the one-shot simple API is enough -- no streaming/dictionary
+ * support is needed here either.
+ */
+let initPromise = null;
+function ensureInit() {
+    if (!initPromise) {
+        initPromise = init();
+    }
+    return initPromise;
+}
+/** Compression level mirrors `ZstdCodec.compressionLevel` (favor decode speed). */
+const COMPRESSION_LEVEL = 3;
+export async function zstdCompress(data) {
+    await ensureInit();
+    return compress(data, COMPRESSION_LEVEL);
+}
+/**
+ * Decompresses a zstd frame and asserts the output is exactly `expectedSize`
+ * bytes (the blob's index-declared `uncompressed_length`), converging on the
+ * Swift `ZstdCodec.decompress(_, originalSize:)` discipline.
+ *
+ * `@bokuweb/zstd-wasm`'s `decompress` takes no target-size argument (it sizes
+ * its output buffer from the frame's own declared content size), so the guard
+ * against a size-lying frame is this exact-length check plus the caller's
+ * declared-size cap (`enforceBlobSizePolicy`). A mismatch throws
+ * `CorruptBlobError` before the bytes are used, ahead of the SHA-256 gate.
+ */
+export async function zstdDecompress(data, expectedSize) {
+    await ensureInit();
+    const out = decompress(data);
+    if (out.length !== expectedSize) {
+        throw new CorruptBlobError(`zstd output length ${out.length} != declared ${expectedSize}`);
+    }
+    return out;
+}
+//# sourceMappingURL=zstd.js.map

package/dist/yom/zstd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd.js","sourceRoot":"","sources":["../../src/yom/zstd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;GAOG;AACH,IAAI,WAAW,GAAyB,IAAI,CAAC;AAE7C,SAAS,UAAU;IACjB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,IAAI,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,mFAAmF;AACnF,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAgB;IACjD,MAAM,UAAU,EAAE,CAAC;IACnB,OAAO,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAgB,EAAE,YAAoB;IACzE,MAAM,UAAU,EAAE,CAAC;IACnB,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,gBAAgB,CAAC,sBAAsB,GAAG,CAAC,MAAM,gBAAgB,YAAY,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "yom-format",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read-only packfile format for scanned books: AVIF pages, FlatBuffers index, OCR + full-text search in a single .yom file",
+  "license": "MIT",
+  "author": "juntaki",
+  "homepage": "https://github.com/juntaki/yom-format",
+  "repository": {
+    "type": "git",
+    "url": "github:juntaki/yom-format",
+    "directory": "web"
+  },
+  "keywords": [
+    "yom",
+    "ebook",
+    "packfile",
+    "flatbuffers",
+    "avif",
+    "ocr",
+    "full-text-search",
+    "pdf"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "yom": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pipeline": {
+      "types": "./dist/pipeline/index.d.ts",
+      "default": "./dist/pipeline/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm run test -- --run && npm run build"
+  },
+  "dependencies": {
+    "@bokuweb/zstd-wasm": "^0.0.27",
+    "@jsquash/avif": "^2.1.1",
+    "flatbuffers": "^25.9.23",
+    "pdfjs-dist": "^6.1.200"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.7",
+    "vitest": "^2.1.8"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * `yom` -- a small, dependency-light CLI for inspecting, verifying, and
+ * extracting from existing `.yom` packfiles.
+ *
+ * Commands: info | verify | ls | extract | meta. `verify` also accepts an
+ * HTTP(S) URL (exercising the Gap-1 ranged reader end-to-end); the others
+ * operate on a local file. PDF -> .yom conversion is intentionally NOT here:
+ * that pipeline is browser-only. Use the web convert tool or the iOS app.
+ *
+ * Command handlers are exported for testability; the process entry point at
+ * the bottom only runs when the file is executed directly.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { YOMPackfileReader } from "./yom/reader.js";
+import { validateYOM } from "./yom/validator.js";
+import { parseHeaderFields } from "./yom/header.js";
+import { YOM_HEADER_SIZE } from "./yom/constants.js";
+import { pdfExportPresent } from "./yom/flatbufferVerify.js";
+import { ReadingDirection } from "./yom/generated/yomu/yom/reading-direction.js";
+import type { MainIndex } from "./yom/generated/yomu/yom/main-index.js";
+import type { OutlineEntry } from "./yom/generated/yomu/yom/outline-entry.js";
+
+export interface CliIO {
+  out(line: string): void;
+  err(line: string): void;
+}
+
+interface ParsedArgs {
+  positionals: string[];
+  json: boolean;
+  page?: number;
+  kind?: string;
+  out?: string;
+}
+
+const VALUE_FLAGS = new Set(["--page", "--kind", "-o", "--out"]);
+
+function parseArgs(args: string[]): ParsedArgs {
+  const parsed: ParsedArgs = { positionals: [], json: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") {
+      parsed.json = true;
+    } else if (VALUE_FLAGS.has(arg)) {
+      const value = args[++i];
+      if (value === undefined) throw new CliUsageError(`missing value for ${arg}`);
+      if (arg === "--page") parsed.page = Number(value);
+      else if (arg === "--kind") parsed.kind = value;
+      else parsed.out = value; // -o | --out
+    } else if (arg.startsWith("-")) {
+      throw new CliUsageError(`unknown flag ${arg}`);
+    } else {
+      parsed.positionals.push(arg);
+    }
+  }
+  return parsed;
+}
+
+class CliUsageError extends Error {}
+
+const USAGE = `yom -- inspect and extract from .yom packfiles
+
+Usage:
+  yom info    <file.yom> [--json]
+  yom verify  <file.yom | url> [--json]
+  yom ls      <file.yom> [--json]
+  yom extract <file.yom> --page N --kind image|thumb|ocr|text -o <out>
+  yom meta    <file.yom>
+
+Note: PDF -> .yom conversion is browser-only; use the web convert tool or the
+iOS app. There is no 'convert' command.`;
+
+function isUrl(target: string): boolean {
+  return /^https?:\/\//i.test(target);
+}
+
+async function loadLocalBytes(path: string): Promise<Uint8Array> {
+  const buf = await readFile(path);
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+
+function readingDirectionName(value: number): string {
+  return ReadingDirection[value] ?? String(value);
+}
+
+/** `info` -- magic, version, sizes, page count, index summary. */
+export async function cmdInfo(args: ParsedArgs, io: CliIO): Promise<number> {
+  const target = args.positionals[0];
+  if (!target) throw new CliUsageError("info requires a <file.yom>");
+  const bytes = await loadLocalBytes(target);
+  const reader = await YOMPackfileReader.open(bytes);
+  const header = parseHeaderFields(bytes.subarray(0, YOM_HEADER_SIZE));
+  const index = reader.mainIndex;
+
+  const info = {
+    magic: new TextDecoder().decode(header.magic),
+    formatVersion: header.formatVersion,
+    fileSize: bytes.length,
+    indexOffset: Number(header.indexOffset),
+    indexLength: Number(header.indexUncompressedLength),
+    pageCount: reader.pageCount,
+    blobCount: index.blobsLength(),
+    title: reader.title,
+    hasOcr: index.ocrLayoutBlobIndex() >= 0,
+    hasNormalizedText: index.normalizedTextBlobIndex() >= 0,
+    hasSearch: index.searchDictionaryBlobIndex() >= 0,
+    searchTermCount: index.searchTermsLength(),
+  };
+
+  if (args.json) {
+    io.out(JSON.stringify(info, null, 2));
+  } else {
+    io.out(`magic:            ${info.magic}`);
+    io.out(`formatVersion:    ${info.formatVersion}`);
+    io.out(`fileSize:         ${info.fileSize}`);
+    io.out(`indexOffset:      ${info.indexOffset}`);
+    io.out(`indexLength:      ${info.indexLength}`);
+    io.out(`title:            ${info.title}`);
+    io.out(`pageCount:        ${info.pageCount}`);
+    io.out(`blobCount:        ${info.blobCount}`);
+    io.out(`hasOcr:           ${info.hasOcr}`);
+    io.out(`hasNormalizedText:${info.hasNormalizedText}`);
+    io.out(`hasSearch:        ${info.hasSearch}`);
+    io.out(`searchTermCount:  ${info.searchTermCount}`);
+  }
+  return 0;
+}
+
+/** `verify` -- full validation for a local file; per-blob ranged verify for a URL. */
+export async function cmdVerify(args: ParsedArgs, io: CliIO): Promise<number> {
+  const target = args.positionals[0];
+  if (!target) throw new CliUsageError("verify requires a <file.yom | url>");
+
+  try {
+    if (isUrl(target)) {
+      // Exercise the ranged reader end-to-end: open reads header+index (with
+      // bounded index verify), then each blob read verifies its own SHA-256.
+      const reader = await YOMPackfileReader.openURL(target, { fallbackToFullFetch: true });
+      for (let i = 0; i < reader.mainIndex.blobsLength(); i++) {
+        await reader.readBlob(i);
+      }
+      report(io, args.json, { ok: true, target, mode: "range-per-blob" });
+    } else {
+      const bytes = await loadLocalBytes(target);
+      await validateYOM(bytes);
+      report(io, args.json, { ok: true, target, mode: "full" });
+    }
+    return 0;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    report(io, args.json, { ok: false, target, reason });
+    return 1;
+  }
+}
+
+/** `ls` -- per-page index, label, dimensions, and page-image blob size. */
+export async function cmdLs(args: ParsedArgs, io: CliIO): Promise<number> {
+  const target = args.positionals[0];
+  if (!target) throw new CliUsageError("ls requires a <file.yom>");
+  const bytes = await loadLocalBytes(target);
+  const reader = await YOMPackfileReader.open(bytes);
+  const index = reader.mainIndex;
+
+  const rows = [];
+  for (let i = 0; i < reader.pageCount; i++) {
+    const page = reader.page(i);
+    const imageBlob = index.blobs(page.pageImageBlobIndex());
+    rows.push({
+      page: i,
+      label: page.pageLabel() ?? "",
+      pixelWidth: page.pixelWidth(),
+      pixelHeight: page.pixelHeight(),
+      imageBlobIndex: page.pageImageBlobIndex(),
+      imageBlobBytes: imageBlob ? Number(imageBlob.compressedLength()) : 0,
+    });
+  }
+  const hasOcr = index.ocrLayoutBlobIndex() >= 0;
+  const hasNormalizedText = index.normalizedTextBlobIndex() >= 0;
+
+  if (args.json) {
+    io.out(JSON.stringify({ pageCount: reader.pageCount, hasOcr, hasNormalizedText, pages: rows }, null, 2));
+  } else {
+    io.out(`pages: ${reader.pageCount}  hasOcr: ${hasOcr}  hasNormalizedText: ${hasNormalizedText}`);
+    io.out("idx  label            WxH           imageBytes");
+    for (const r of rows) {
+      io.out(
+        `${String(r.page).padEnd(4)} ${r.label.padEnd(16)} ${`${r.pixelWidth}x${r.pixelHeight}`.padEnd(13)} ${r.imageBlobBytes}`,
+      );
+    }
+  }
+  return 0;
+}
+
+/** `extract` -- write one blob (page image/thumbnail, or file-wide ocr/text) to disk. */
+export async function cmdExtract(args: ParsedArgs, io: CliIO): Promise<number> {
+  const target = args.positionals[0];
+  if (!target) throw new CliUsageError("extract requires a <file.yom>");
+  if (!args.kind) throw new CliUsageError("extract requires --kind image|thumb|ocr|text");
+  if (!args.out) throw new CliUsageError("extract requires -o <out>");
+  const bytes = await loadLocalBytes(target);
+  const reader = await YOMPackfileReader.open(bytes);
+  const index = reader.mainIndex;
+
+  let data: Uint8Array;
+  switch (args.kind) {
+    case "image":
+      requirePage(args);
+      data = await reader.pageImage(args.page!);
+      break;
+    case "thumb":
+      requirePage(args);
+      data = await reader.thumbnailImage(args.page!);
+      break;
+    case "ocr":
+      data = await readFileWideBlob(reader, index.ocrLayoutBlobIndex(), "ocr");
+      break;
+    case "text":
+      data = await readFileWideBlob(reader, index.normalizedTextBlobIndex(), "normalized text");
+      break;
+    default:
+      throw new CliUsageError(`unknown --kind ${args.kind} (expected image|thumb|ocr|text)`);
+  }
+
+  await writeFile(args.out, data);
+  io.out(`wrote ${data.length} bytes to ${args.out}`);
+  return 0;
+}
+
+/** `meta` -- book metadata + page labels + outline (when present) as JSON. */
+export async function cmdMeta(args: ParsedArgs, io: CliIO): Promise<number> {
+  const target = args.positionals[0];
+  if (!target) throw new CliUsageError("meta requires a <file.yom>");
+  const bytes = await loadLocalBytes(target);
+  const reader = await YOMPackfileReader.open(bytes);
+  const index = reader.mainIndex;
+  const book = index.book();
+
+  const pageLabels: string[] = [];
+  for (let i = 0; i < reader.pageCount; i++) {
+    pageLabels.push(reader.page(i).pageLabel() ?? "");
+  }
+
+  const header = parseHeaderFields(bytes.subarray(0, YOM_HEADER_SIZE));
+  const indexOffset = Number(header.indexOffset);
+  const indexBytes = bytes.subarray(indexOffset, indexOffset + Number(header.indexUncompressedLength));
+
+  const meta = {
+    title: reader.title,
+    pageCount: book ? book.pageCount() : reader.pageCount,
+    readingDirection: book ? readingDirectionName(book.readingDirection()) : null,
+    createdAtUnix: book ? book.createdAtUnix().toString() : null,
+    pageLabels,
+    outline: pdfExportPresent(indexBytes) ? readOutline(index) : [],
+  };
+
+  io.out(JSON.stringify(meta, null, 2));
+  return 0;
+}
+
+interface OutlineNode {
+  title: string;
+  pageId: number;
+  children: OutlineNode[];
+}
+
+function readOutline(index: MainIndex): OutlineNode[] {
+  const pdf = index.pdfExport();
+  if (!pdf) return [];
+  const nodes: OutlineNode[] = [];
+  for (let i = 0; i < pdf.outlineLength(); i++) {
+    const entry = pdf.outline(i);
+    if (entry) nodes.push(readOutlineEntry(entry));
+  }
+  return nodes;
+}
+
+function readOutlineEntry(entry: OutlineEntry): OutlineNode {
+  const children: OutlineNode[] = [];
+  for (let i = 0; i < entry.childrenLength(); i++) {
+    const child = entry.children(i);
+    if (child) children.push(readOutlineEntry(child));
+  }
+  return { title: entry.title() ?? "", pageId: entry.pageId(), children };
+}
+
+function requirePage(args: ParsedArgs): void {
+  if (args.page === undefined || !Number.isInteger(args.page) || args.page < 0) {
+    throw new CliUsageError("extract --kind image|thumb requires --page N (a non-negative integer)");
+  }
+}
+
+async function readFileWideBlob(reader: YOMPackfileReader, blobIndex: number, label: string): Promise<Uint8Array> {
+  if (blobIndex < 0) throw new CliUsageError(`this file has no ${label} blob`);
+  return reader.readBlob(blobIndex);
+}
+
+function report(io: CliIO, json: boolean, payload: Record<string, unknown>): void {
+  if (json) {
+    io.out(JSON.stringify(payload));
+    return;
+  }
+  if (payload.ok) io.out(`OK  ${payload.target}${payload.mode ? ` (${payload.mode})` : ""}`);
+  else io.err(`FAIL  ${payload.target}: ${payload.reason}`);
+}
+
+/**
+ * Dispatches a parsed argv to a command handler. Returns the process exit
+ * code (0 ok, non-zero on failure / bad args). Never throws for usage
+ * errors -- they are reported and mapped to exit code 2.
+ */
+export async function runCli(argv: string[], io: CliIO): Promise<number> {
+  const command = argv[0];
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    io.out(USAGE);
+    return command ? 0 : 2;
+  }
+
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(argv.slice(1));
+  } catch (err) {
+    io.err(err instanceof Error ? err.message : String(err));
+    io.err(USAGE);
+    return 2;
+  }
+
+  try {
+    switch (command) {
+      case "info":
+        return await cmdInfo(args, io);
+      case "verify":
+        return await cmdVerify(args, io);
+      case "ls":
+        return await cmdLs(args, io);
+      case "extract":
+        return await cmdExtract(args, io);
+      case "meta":
+        return await cmdMeta(args, io);
+      case "convert":
+        io.err("PDF -> .yom conversion is browser-only; use the web convert tool or the iOS app.");
+        return 2;
+      default:
+        io.err(`unknown command: ${command}`);
+        io.err(USAGE);
+        return 2;
+    }
+  } catch (err) {
+    if (err instanceof CliUsageError) {
+      io.err(err.message);
+      return 2;
+    }
+    io.err(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+const consoleIO: CliIO = {
+  out: (line) => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+};
+
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  runCli(process.argv.slice(2), consoleIO)
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      consoleIO.err(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+}