document-cli 1.1.0 → 1.2.0

package/README.md

@@ -41,7 +41,7 @@ graph TD
 
 ## Why
 
-`documents.js` is a library, not a tool — everything it does happens through function calls from TypeScript/JavaScript. Most people who want to convert a docx to a PDF, extract an `.odb` table to CSV, or poke at a PDF's structure from a terminal don't want to write a script to do it. `document-cli` is that missing entry point: every one of documents.js's 19 direct conversion pairs, its generic converter, its `.odm`/`.odb` extraction functions, and its PDF inspector become a single command-line invocation, and its six live-view editors (docx/pptx/odt/odp/ods/odg) become a keyboard-driven terminal app that never needs a code editor open at all.
+`documents.js` is a library, not a tool — everything it does happens through function calls from TypeScript/JavaScript. Most people who want to convert a docx to a PDF, extract an `.odb` table to CSV, or poke at a PDF's structure from a terminal don't want to write a script to do it. `document-cli` is that missing entry point: every one of documents.js's 27 direct conversion pairs, its generic converter, its `.odm`/`.odb` extraction functions, and its PDF inspector become a single command-line invocation, and its six live-view editors (docx/pptx/odt/odp/ods/odg) plus its line-based markdown editor become a keyboard-driven terminal app that never needs a code editor open at all.
 
 The CLI and the TUI are deliberately not two separate implementations of the same logic. The TUI's own document-opening, saving, and PDF-export code (`src/tui/format/`) calls the identical `documents.js` functions the CLI commands call — `openDocx`/`createDocx`/`docxToPdf` and their five siblings per format, plus `readOdbTables`/`readPdf` for the two read-only sources — so there is exactly one place either surface can drift from what documents.js itself does: nowhere.
 
@@ -68,7 +68,7 @@ cat report.docx | document-cli docx-to-pdf - - > report.pdf
 
 ### Commands
 
-**The 19 explicit `<source>-to-<target>` conversions** — one command per pair `createLocalDocumentConverter().conversions` declares in `documents.js`: `docx-to-pdf`, `pptx-to-pdf`, `odt-to-pdf`, `odp-to-pdf`, `ods-to-pdf`, `odg-to-pdf`, `odf-to-pdf` (one-way, no `pdf-to-odf` — see documents.js's own README), `pdf-to-docx`, `pdf-to-pptx`, `pdf-to-odt`, `pdf-to-odp`, `pdf-to-ods`, `pdf-to-odg`, and the six PDF-bypassing bridges `odt-to-docx`, `docx-to-odt`, `odp-to-pptx`, `pptx-to-odp`, `ods-to-xlsx`, `xlsx-to-ods`. Each takes `<input> [output]`:
+**The 27 explicit `<source>-to-<target>` conversions** — one command per pair `createLocalDocumentConverter().conversions` declares in `documents.js` (confirmed by running the built CLI's own `formats` command, not assumed): the nine `<format>-to-pdf` conversions `docx-to-pdf`, `pptx-to-pdf`, `odt-to-pdf`, `odp-to-pdf`, `ods-to-pdf`, `odg-to-pdf`, `odf-to-pdf`, `xlsx-to-pdf`, `markdown-to-pdf`; the eight `pdf-to-<format>` reverse conversions `pdf-to-docx`, `pdf-to-pptx`, `pdf-to-odt`, `pdf-to-odp`, `pdf-to-ods`, `pdf-to-odg`, `pdf-to-xlsx`, `pdf-to-markdown` (`odf-to-pdf` is one-way — there is no `pdf-to-odf` — see documents.js's own README); and ten further PDF-bypassing bridges, `odt-to-docx`, `docx-to-odt`, `odp-to-pptx`, `pptx-to-odp`, `ods-to-xlsx`, `xlsx-to-ods`, `markdown-to-docx`, `docx-to-markdown`, `markdown-to-odt`, `odt-to-markdown`. Each takes `<input> [output]`:
 
 ```sh
 document-cli docx-to-pdf report.docx report.pdf
@@ -82,7 +82,15 @@ document-cli convert report.docx report.pdf
 document-cli convert report.docx - --to pdf > report.pdf
 ```
 
-**`formats`** — lists every `source -> target` pair the commands above support (`--json` for a machine-readable array), plus a pointer to the commands not on that list because they don't fit the source/target shape (`odm-to-pdf`, `odb-to-csv`, `odb-to-xlsx`, `odb-tables`, `pdf-inspect`).
+**`formats`** — lists every `source -> target` pair the commands above support (`--json` for a machine-readable array), plus a pointer to the commands not on that list because they don't fit the source/target shape (`odm-to-pdf`, `odb-to-csv`, `odb-to-xlsx`, `odb-tables`, `odb-forms`, `odb-reports`, `pdf-inspect`, `from-package`).
+
+**`from-package <input> [output]`** — reads back a `DocumentPackage` JSON file a previous conversion wrote via `--dump-package` (below) and exports it to a real target format, closing the round trip `--dump-package` otherwise has no return path for. Target resolution matches `convert`: an output path's own extension, or `--to <format>` when it doesn't have one. `pdf` writes the package's own `layout` half directly (`writePdf`); every other format builds a fresh package from the `content` half through the identical `buildXPackage` function the matching `pdf-to-X`/bridge conversion already uses. `xlsx` and `odf` are rejected outright — documents.js exposes no `ContentDocument`-to-xlsx builder (convert to `ods` and run `ods-to-xlsx` instead) and a formula document has no write path from `ContentDocument` at all. Only a file genuinely written by `--dump-package` round-trips here; anything else fails with its `$schema` mismatch named:
+
+```sh
+document-cli docx-to-pdf report.docx report.pdf --dump-package report.package.json
+document-cli from-package report.package.json report2.pdf
+document-cli from-package report.package.json report.odt --to odt
+```
 
 **`odm-to-pdf <input> [output]`** — converts a `.odm` master document to PDF. A `.odm`'s chapters are external references to standalone `.odt` files, never inlined in the master document itself, so this command needs to be told where to find them: `--chapters-dir <dir>` (matched by each chapter's own basename) and/or repeatable `--chapter <href>=<file>` overrides. An unresolved chapter fails with every missing `href` named at once, not just the first.
 
@@ -93,6 +101,13 @@ document-cli odb-tables customers.odb
 document-cli odb-to-csv customers.odb --table CUSTOMERS customers.csv
 ```
 
+**`odb-forms <input>`**, **`odb-reports <input>`** — read a `.odb`'s form and report *structure* rather than its table data. A form or report is a static ODF sub-document inside the package, so neither command consults the embedded database at all: they work on an `.odb` whose connection points at an external server just as well as on an embedded one. `odb-forms` prints each form's own data source (table or saved query) and its field-bound controls, sub-forms nested under their parent with their own separate command; `odb-reports` prints each report's data-source command, its band structure (report/page headers and footers, groups, detail), every `rpt:` formula expression (`field:[AMOUNT]`, `rpt:SUM([AMOUNT])`), and any user-defined report functions. `--json` emits the same structure machine-readably — for a form that is the structure only, with the form's own parsed sub-document dropped:
+
+```sh
+document-cli odb-forms sales.odb
+document-cli odb-reports sales.odb --json
+```
+
 **`pdf-inspect <input>`** — reports a PDF's page count, per-page size and item-kind histogram, document metadata, and embedded image formats, without converting it to anything. `--full` dumps the entire parsed `LayoutDocument` as JSON instead of the summary:
 
 ```sh
@@ -104,7 +119,7 @@ document-cli pdf-inspect report.pdf --json
 
 ### Shared flags
 
-The 19 explicit conversions, `convert`, `odm-to-pdf`, `odb-to-xlsx`, and `odb-to-csv` — every command that reads one file and writes one — share:
+The 27 explicit conversions, `convert`, `odm-to-pdf`, `odb-to-xlsx`, and `odb-to-csv` — every command that reads one file and writes one — share:
 
 | Flag | Meaning |
 |---|---|
@@ -114,7 +129,24 @@ The 19 explicit conversions, `convert`, `odm-to-pdf`, `odb-to-xlsx`, and `odb-to
 | `-q, --quiet` | Suppress diagnostic and summary output (the JSON result-summary line still prints in `--json` mode, so a script consuming NDJSON always gets a terminating record). |
 | `--verbose` | Include a full stack trace in the error line when the run fails. |
 
-`--dump-package <file>` is one flag further, registered only on the 19 explicit conversions and `convert` — it writes the intermediate `DocumentPackage` (content + layout) that conversion built to a JSON file. Every conversion populates one except `odf-to-pdf`, which accepts but never invokes its own `onDocument` callback (a standalone formula document has no `ContentDocument`/`LayoutDocument` pivot behind it); the six PDF-bypassing bridges populate one too, just with `layout` always `undefined`, since a bridge never runs a layout engine. `odm-to-pdf`/`odb-*` don't expose the flag at all, since neither goes through `DocumentConverter.convert` in the first place. `odb-tables`, `formats`, and `pdf-inspect` each take only their own `--json` (plus `pdf-inspect`'s own `--full`); `tui` takes no flags at all, only an optional positional file.
+`--dump-package <file>` is one flag further, registered only on the 27 explicit conversions and `convert` — it writes the intermediate `DocumentPackage` (content + layout) that conversion built to a JSON file, tagged with its own `$schema` so `from-package` (above) can read it back in. Every conversion populates one except `odf-to-pdf`, which accepts but never invokes its own `onDocument` callback (a standalone formula document has no `ContentDocument`/`LayoutDocument` pivot behind it); the ten PDF-bypassing bridges (`odt-to-docx`/`docx-to-odt`, `odp-to-pptx`/`pptx-to-odp`, `ods-to-xlsx`/`xlsx-to-ods`, `markdown-to-docx`/`docx-to-markdown`, `markdown-to-odt`/`odt-to-markdown`) populate one too, just with `layout` always `undefined`, since a bridge never runs a layout engine. `odm-to-pdf`/`odb-*` don't expose the flag at all, since neither goes through `DocumentConverter.convert` in the first place. `odb-tables`, `odb-forms`, `odb-reports`, `formats`, and `pdf-inspect` each take only their own `--json` (plus `pdf-inspect`'s own `--full`); `from-package` takes `--to <format>` alongside the shared flags in this table; `tui` takes no flags at all, only an optional positional file.
+
+### Real fonts
+
+By default a conversion renders through whatever `documents.js` resolves for itself: the source document's own embedded faces first, then `pdf-codec`'s vendored Carlito/Caladea substitutes (metric-compatible with Calibri/Cambria), then the standard 14 PDF fonts. `--font-file <path>` inserts your own faces between the first two steps — used wherever the document asks for the family a font file declares, and ignored where it doesn't.
+
+```sh
+document-cli docx-to-pdf report.docx report.pdf \
+  --font-file ~/fonts/Calibri.ttf \
+  --font-file ~/fonts/Calibri-Bold.ttf \
+  --report-font-substitutions
+```
+
+The flag is repeatable, takes a `.ttf`/`.otf` path, and needs **no accompanying family flag**: the family, weight, and slope are read from the font file's own `name` and `OS/2` tables. That is a deliberate choice over the alternative of a parallel `--font-family`/`--font-bold`/`--font-italic` set — three repeatable flags whose values must stay index-aligned with a fourth is a silent-misalignment hazard (pass two font files and one `--font-family` and the second face is mis-declared, with nothing reporting it), and every real font already states all three facts itself. The consequence to know about: a font file can only be supplied *as the family it says it is*. There is no way to say "draw Calibri using this file instead" — for that, the family in the document has to match the family in the font. A file that is not a readable font (a `.woff`, a `.ttc` collection, a mistyped path pointing at something else) fails the run outright, naming the file, rather than being quietly skipped.
+
+`--report-font-substitutions` prints each face that resolved to something other than what the document asked for, as it happens, with its structured fields intact (`--json` makes it one more NDJSON record: `{"type":"font-substitution","requestedFamily":"Calibri",…}`). Without it, the same fallbacks are still reported — the `font/substituted` diagnostic lines every conversion already emits — just as rendered messages after the fact rather than structured events as they occur.
+
+Both flags are registered only where they can do something: the nine `<format>-to-pdf` conversions, `convert`, and `odm-to-pdf`. A `pdf-to-<format>` reconstruction reads a PDF's own already-positioned glyphs and a format-to-format bridge runs no layout engine at all, so neither resolves a typeface and neither advertises the flags.
 
 Diagnostics and the summary line always go to stderr; stdout is reserved for the converted bytes on any command writing to `-`.
 
@@ -133,7 +165,13 @@ Diagnostics and the summary line always go to stderr; stdout is reserved for the
 
 Launch it either bare (`document-cli`, with no arguments) or explicitly with `document-cli tui [file]` — both open the same app; the explicit form additionally opens `file` immediately, skipping the launcher screen. The TUI needs an interactive terminal: a bare invocation with redirected stdout prints help text instead, and an explicit `tui` invocation with redirected stdout fails outright, since there's no terminal for Ink to draw into.
 
-It supports the same six formats documents.js's editors cover — docx, pptx, odt, odp, ods, odg — each with a full navigate/edit/save experience built on that format's live-view editor (paragraphs and runs for docx/odt, slides and shapes for pptx/odp, sheets and cells for ods, pages and vectors/shapes for odg), plus undo (whole-document snapshots taken before each committed mutation), search, a command palette, and PDF export straight from the open document. Two further formats open read-only: a `.odb` browses its tables and rows with no write path at all (documents.js's own `.odb` support has no write direction to offer), and a `.pdf` browses its pages and positioned items rather than being edited in place. `.xlsx` and standalone `.odf` have no TUI editor — documents.js has no xlsx editor at all, and a standalone `.odf` formula document has nothing to edit interactively, only a PDF conversion.
+It supports the same six formats documents.js's live-view editors cover — docx, pptx, odt, odp, ods, odg — each with a full navigate/edit/save experience built on that format's editor (paragraphs and runs for docx/odt, slides and shapes for pptx/odp, sheets and cells for ods, pages and vectors/shapes for odg), plus undo (whole-document snapshots taken before each committed mutation), search, a command palette, and PDF export straight from the open document. On a pptx or odp slide, `a` from the shape list also adds a real table (rows then columns, a two-step prompt) alongside the existing textbox/image choices, and `n` opens the slide's own speaker notes for either format — `PptxSlide` and `OdpSlide` both carry a real `.notes` getter/setter, so notes editing was never odp-specific, only gated that way until this phase removed the gate.
+
+Markdown (`.md`/`.markdown`) is also a fully supported TUI format, but a structurally different one: documents.js has no `MarkdownEditor` the way it has a `DocxEditor`/`OdtEditor` (its own markdown support is a thin read/write pair over a plain string, not an `XmlElement` tree to hold a live view into), so the TUI edits a markdown document as its own raw source text rather than through a live-view editor object. Opening a `.md` file loads its bytes verbatim as a source string (`decodeMarkdownText`); the root screen lists that source split into lines, one row each, with search filtering by line content; selecting a line opens a line editor that replaces its text in place; `Ctrl+S` writes the (possibly edited) source straight back to disk (`encodeMarkdownText`), the identical byte↔text boundary opening it went through in reverse — never through `readMarkdownContent`/`buildMarkdownText`. PDF export is the one place the `ContentDocument` pivot enters at all: exporting calls `markdownToPdf` directly on the current source text, run fresh on every export rather than kept in sync with in-progress edits. There is no "create a new markdown document" flow (documents.js has no `createMarkdown()`), so a markdown document can only be opened from an existing file, never created fresh from the TUI's new-document screen the way docx/pptx/odt/odp/ods/odg can.
+
+Three further formats open read-only: a `.odb` browses its tables and rows with no write path at all (documents.js's own `.odb` support has no write direction to offer), a `.pdf` browses its pages and positioned items rather than being edited in place, and a `.xlsx` opens as a converted PDF preview — documents.js has no xlsx editor to hold a live view into, so opening one runs `xlsxToPdf` once at open time and browses the result through the identical page-list/page-items/item-detail screens a real `.pdf` uses, with the original bytes kept alongside so a later export re-runs `xlsxToPdf` with the caller's own fonts and diagnostics rather than reusing the fixed preview conversion. A `.odb` additionally browses its *structure* alongside its data: `f` from the table list opens the form browser and `r` the report browser, each listing what the database declares and opening one to show it in full — a form's own data source and field-bound controls (sub-forms nested under their parent), a report's data-source command, band and group structure, and every `rpt:` formula. Both are rendered through the same `src/odb-structure.ts` the `odb-forms`/`odb-reports` commands print, so the two views cannot drift apart, and search filters by line (`/SUM` narrows a long report to its aggregate expressions). A standalone `.odf` formula document has no TUI editor either — nothing to edit interactively, only a PDF conversion.
+
+The export-to-PDF screen (`e` from any editor screen) is a two-field form: a destination path, then an optional comma-separated list of local `.ttf`/`.otf` paths, which are the same `--font-file` faces the CLI takes and are derived the same way — each font's family, weight, and slope come from the file itself. `Enter` on the path field moves to the fonts field and `Enter` there exports, so leaving fonts empty is still "type a path, press Enter twice". Comma-separated rather than space-separated because a font path routinely contains spaces and almost never a comma. A face falling back to a substitute is reported into the same diagnostics panel a character substitution already is, and a bad font path fails the export with the file named, before anything is written to the destination.
 
 ### Key bindings
 
@@ -160,7 +198,7 @@ The global bindings below apply everywhere; individual screens (a docx run's own
 
 The package splits into two independent layers sharing one thin format-detection module, `src/format.ts` (extension ⇄ `DocumentFormat` inference), so a change to how a format is recognised from a path never needs making twice:
 
-- **`src/commands/` + `src/runtime/`** is the CLI proper. `commands/shared.ts`'s `buildConversionAction(source, target)` is the one implementation behind every `<source>-to-<target>` command and the generic `convert` — it partially applies a format pair and hands back a ready commander action, so the conversion-running logic (read input, call `createLocalDocumentConverter().convert`, write output, report diagnostics, map errors to exit codes) exists exactly once regardless of which of the 19 pairs is invoked. `commands/{odm,odb,pdf-inspect}.ts` each call their own documents.js function directly instead, since none of the three fits the generic `DocumentConverter` port's bytes-in/bytes-out shape (`odmToPdf` needs a `resolveSubDocument` callback, `.odb` extraction has no PDF conversion or port entry at all, and `pdf-inspect` reads without converting). `src/runtime/` holds the process-level concerns every command shares: `abort.ts`'s `createRuntimeSignal` (one `SIGINT` listener and an optional timeout, combined into a single signal), `io.ts`'s stdin/stdout/file `-`-aware read and write helpers, `exit-codes.ts`'s exit-code constants and `mapErrorToExit`, and `diagnostics.ts`'s stderr reporter.
+- **`src/commands/` + `src/runtime/`** is the CLI proper. `commands/shared.ts`'s `buildConversionAction(source, target)` is the one implementation behind every `<source>-to-<target>` command and the generic `convert` — it partially applies a format pair and hands back a ready commander action, so the conversion-running logic (read input, call `createLocalDocumentConverter().convert`, write output, report diagnostics, map errors to exit codes) exists exactly once regardless of which of the 27 pairs is invoked. `commands/{odm,odb,pdf-inspect}.ts` each call their own documents.js function directly instead, since none of the three fits the generic `DocumentConverter` port's bytes-in/bytes-out shape (`odmToPdf` needs a `resolveSubDocument` callback, `.odb` extraction has no PDF conversion or port entry at all, and `pdf-inspect` reads without converting). `src/odb-structure.ts` sits alongside `src/format.ts` as the second module both layers share: it turns an `OdbForm`/`OdbReport` into a flat array of already-indented lines, which the `odb-forms`/`odb-reports` commands join with newlines and the TUI's own form/report detail screens render one per list row. `src/runtime/` holds the process-level concerns every command shares: `abort.ts`'s `createRuntimeSignal` (one `SIGINT` listener and an optional timeout, combined into a single signal), `io.ts`'s stdin/stdout/file `-`-aware read and write helpers, `exit-codes.ts`'s exit-code constants and `mapErrorToExit`, and `diagnostics.ts`'s stderr reporter.
 - **`src/tui/`** is the Ink app, entered lazily. `src/cli.ts` only imports `./tui/index.js` inside a dynamic `import()`, called just once dispatch has already decided the TUI is actually running — a plain `document-cli docx-to-pdf a b` invocation never loads React, Ink, or any TUI screen module at all, and `tsdown.config.ts`'s bin build correctly code-splits the TUI into its own lazily-loaded chunk as a result. Inside the TUI, `state/reducer.ts` and `state/types.ts` hold the single `AppState` (a screen stack, the open document, undo history, overlays), `format/open-document.ts` is the one place bytes become an open document for every format, and `screens/editors/<format>/` holds each format's own screen components — reusing shared building blocks (`screens/shared/paragraph-family.tsx`, `slide-family.tsx`) between docx/odt and pptx/odp respectively, the same way documents.js's own odp editor reuses its odt paragraph/run classes.
 - **`src/index.ts`** re-exports the CLI's command-layer, format, and exit-code logic (not the TUI, which stays behind its own lazy import) as this package's `"."` library export, for a caller that wants `document-cli`'s conversion-running logic directly rather than spawning the bin as a subprocess.
 - **One package, two npm names.** `package.json`'s `bin` field lists `document-cli` and `doculi` unconditionally, both pointing at the same built entry point — there is no separate build, alias package, or npm alias mechanism involved, just two keys in one `bin` object.
@@ -178,7 +216,7 @@ pnpm test:smoke    # tsdown, then vitest run --project smoke -- spawns the built
 
 ## Gotchas
 
-- **The lazy TUI import is load-bearing, not incidental.** `src/cli.ts` computes the dispatch token before doing anything else and only reaches `await import('./tui/index.js')` on the bare/`tui` branch — every other command path (all 19 explicit conversions, `convert`, `formats`, `odm-to-pdf`, `odb-*`, `pdf-inspect`) never touches that import at all. This is what keeps a scripted, high-frequency CLI invocation from paying React/Ink's module-load cost on every call.
+- **The lazy TUI import is load-bearing, not incidental.** `src/cli.ts` computes the dispatch token before doing anything else and only reaches `await import('./tui/index.js')` on the bare/`tui` branch — every other command path (all 27 explicit conversions, `convert`, `formats`, `odm-to-pdf`, `odb-*`, `pdf-inspect`) never touches that import at all. This is what keeps a scripted, high-frequency CLI invocation from paying React/Ink's module-load cost on every call.
 - **A bare invocation and an explicit `tui` invocation fail differently on non-interactive stdout.** `document-cli` with no arguments and redirected stdout prints help and exits `0`, on the assumption that a bare invocation piped somewhere was more likely a forgotten argument than a deliberate TUI request. `document-cli tui` with redirected stdout is unambiguous, so it fails outright (exit `2`) rather than silently reinterpreting it as a help request.
 - **`tsdown.config.ts` disables `fixedExtension` on both build passes.** `platform: 'node'` defaults tsdown's `fixedExtension` to `true`, which would emit `dist/cli.mjs`/`dist/index.mjs` regardless of `package.json`'s own `"type": "module"` — mismatching the `.js`/`.cjs` paths `bin` and `exports` actually name. Both entries set `fixedExtension: false` explicitly so the build output matches what's published.
 - **`readOdbTables` needs `decodePackage` from `odf.js`, not from `documents.js`.** `documents.js` re-exports `ooxml.js`'s own `decodePackage` under the same name for OOXML packages, and that function cannot read an ODF `.odb` container at all — `commands/odb.ts` and the TUI's `format/open-document.ts` both import `decodePackage` from `odf.js` directly for exactly this reason. Importing it from the wrong package fails silently different, not loudly: it throws trying to parse a `.odb`'s manifest as an OOXML relationship file.

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { a as inferFormatFromExtension, n as resolveDefaultOutputPath, o as isDocumentFormat, r as writeOutput, t as readInput } from "./io-CKOE9Xda.js";
+import { a as odbFormSummary, c as writeOutput, d as inferFormatFromExtension, f as isDocumentFormat, i as formatOdbReportLines, l as loadProvidedFonts, n as describeOdbReport, o as readInput, r as formatOdbFormLines, s as resolveDefaultOutputPath, t as describeOdbForm } from "./odb-structure-CX_0zL8_.js";
 import { Command, CommanderError, InvalidArgumentError } from "commander";
 import { writeFile } from "node:fs/promises";
-import { OdbNoEmbeddedDataSourceError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, createLocalDocumentConverter, odbToCsv, odbToXlsx, odmToPdf, readOdbTables, readPdf } from "documents.js";
+import { OdbNoEmbeddedDataSourceError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, UnrecognizedDocumentSchemaError, buildDocxPackage, buildMarkdownText, buildOdgPackage, buildOdpPackage, buildOdsPackage, buildOdtPackage, buildPptxPackage, createLocalDocumentConverter, documentFromJson, documentPackageWithSchema, encodeMarkdownText, encodePackage, odbToCsv, odbToXlsx, odmToPdf, readOdbForms, readOdbReports, readOdbTables, readPdf, writePdf } from "documents.js";
 import { basename, dirname, extname, join } from "node:path";
-import { decodePackage } from "odf.js";
+import { decodePackage, encodePackage as encodePackage$1 } from "odf.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/runtime/abort.ts
 function combineSignals(a, b) {
@@ -72,6 +72,22 @@ function createDiagnosticReporter(options) {
 		}
 	};
 }
+function createFontSubstitutionReporter(options) {
+	const { json, quiet, command } = options;
+	return (substitution) => {
+		if (quiet) return;
+		if (json) {
+			process.stderr.write(`${JSON.stringify({
+				type: "font-substitution",
+				command,
+				...substitution
+			})}\n`);
+			return;
+		}
+		const styleClause = `${substitution.requestedBold ? " bold" : ""}${substitution.requestedItalic ? " italic" : ""}`;
+		process.stderr.write(`[${command}] font substitution: "${substitution.requestedFamily}"${styleClause} -> "${substitution.resolvedFamily}" (${substitution.reason})\n`);
+	};
+}
 function substitutionToDiagnostic(substitution, pageIndex) {
 	return {
 		severity: "warning",
@@ -80,6 +96,13 @@ function substitutionToDiagnostic(substitution, pageIndex) {
 		pageIndex
 	};
 }
+function fontSubstitutionToDiagnostic(substitution) {
+	return {
+		severity: "info",
+		code: "font/substituted",
+		message: `"${`${substitution.requestedFamily}${substitution.requestedBold ? " bold" : ""}${substitution.requestedItalic ? " italic" : ""}`}" is not available; ${substitution.reason === "vendored-substitute" ? `substituted the metric-compatible "${substitution.resolvedFamily}"` : `substituted another face of "${substitution.resolvedFamily}"`}`
+	};
+}
 function pdfDiagnosticToDiagnostic(diagnostic) {
 	return {
 		severity: diagnostic.severity,
@@ -97,6 +120,18 @@ function mapErrorToExit(error, abortReason) {
 }
 //#endregion
 //#region src/commands/shared.ts
+const KNOWN_DOCUMENT_FORMATS = "docx, pptx, xlsx, odt, odp, ods, odg, odf, markdown, pdf";
+function resolveTargetFormat(output, out, to) {
+	if (to !== void 0) {
+		if (!isDocumentFormat(to)) return { errorMessage: `unknown --to format '${to}'; expected one of ${KNOWN_DOCUMENT_FORMATS}` };
+		return { format: to };
+	}
+	const destination = output ?? out;
+	if (destination === void 0) return { errorMessage: "cannot infer a target format -- pass an output path with a recognised extension, --out with one, or --to <format>" };
+	const inferred = inferFormatFromExtension(destination);
+	if (inferred === void 0) return { errorMessage: `cannot infer a target format from '${destination}'; pass --to <format> instead` };
+	return { format: inferred };
+}
 function formatError(error, verbose) {
 	if (!(error instanceof Error)) return `error: ${String(error)}`;
 	const stackClause = verbose && error.stack !== void 0 ? `\n${error.stack}` : "";
@@ -113,13 +148,22 @@ function buildConversionAction(source, target) {
 		const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeoutMs });
 		try {
 			const inputBytes = await readInput(input, { signal });
+			const fonts = await loadProvidedFonts(options.fontFiles ?? [], { signal });
 			const result = await createLocalDocumentConverter().convert({
 				source: {
 					format: source,
 					bytes: new Uint8Array(inputBytes)
 				},
 				targetFormat: target
-			}, { signal });
+			}, {
+				signal,
+				fonts,
+				onFontSubstitution: options.reportFontSubstitutions === true ? createFontSubstitutionReporter({
+					json: options.json,
+					quiet: options.quiet,
+					command
+				}) : void 0
+			});
 			await writeOutput(resolvedOutput, result.document.bytes);
 			const reporter = createDiagnosticReporter({
 				json: options.json,
@@ -128,7 +172,7 @@ function buildConversionAction(source, target) {
 			});
 			for (const diagnostic of result.diagnostics) reporter.report(diagnostic);
 			if (options.dumpPackage !== void 0) if (result.package === void 0) process.stderr.write(`[${command}] this conversion does not produce an intermediate DocumentPackage\n`);
-			else await writeFile(options.dumpPackage, JSON.stringify(result.package, void 0, 2));
+			else await writeFile(options.dumpPackage, JSON.stringify(documentPackageWithSchema(result.package), void 0, 2));
 			reporter.summarize({
 				output: resolvedOutput,
 				bytes: result.document.bytes.byteLength,
@@ -161,6 +205,14 @@ function addVerboseOption(command) {
 function addDumpPackageOption(command) {
 	return command.option("--dump-package <file>", "write the intermediate DocumentPackage (content + layout) this conversion built to a JSON file");
 }
+function collectFontFile(value, previous) {
+	return [...previous, value];
+}
+function addFontOptions(command) {
+	command.option("--font-file <path>", "embed this font file (.ttf/.otf) when the document asks for the family it declares; repeatable. The family, weight, and slope are read from the font's own 'name'/'OS/2' tables, so no accompanying family flag is needed", collectFontFile, []);
+	command.option("--report-font-substitutions", "print each font face that resolved to something other than what the document asked for to stderr, as it happens", false);
+	return command;
+}
 function addConversionFlags(command) {
 	addOutOption(command);
 	addTimeoutOption(command);
@@ -178,21 +230,11 @@ function toConversionCommandOptions(options) {
 		json: options.json,
 		quiet: options.quiet,
 		verbose: options.verbose,
-		dumpPackage: options.dumpPackage
+		dumpPackage: options.dumpPackage,
+		fontFiles: options.fontFile,
+		reportFontSubstitutions: options.reportFontSubstitutions
 	};
 }
-const KNOWN_FORMATS = "docx, pptx, xlsx, odt, odp, ods, odg, odf, markdown, pdf";
-function resolveGenericTarget(output, options) {
-	if (options.to !== void 0) {
-		if (!isDocumentFormat(options.to)) return { errorMessage: `unknown --to format '${options.to}'; expected one of ${KNOWN_FORMATS}` };
-		return { format: options.to };
-	}
-	const destination = output ?? options.out;
-	if (destination === void 0) return { errorMessage: "cannot infer a target format -- pass an output path with a recognised extension, --out with one, or --to <format>" };
-	const inferred = inferFormatFromExtension(destination);
-	if (inferred === void 0) return { errorMessage: `cannot infer a target format from '${destination}'; pass --to <format> instead` };
-	return { format: inferred };
-}
 async function runGenericConvert(input, output, options) {
 	const extension = extname(input).toLowerCase();
 	if (extension === ".odm") {
@@ -205,10 +247,10 @@ async function runGenericConvert(input, output, options) {
 	}
 	const source = inferFormatFromExtension(input);
 	if (source === void 0) {
-		process.stderr.write(`convert: cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_FORMATS}) or use one of the explicit '<source>-to-<target>' commands\n`);
+		process.stderr.write(`convert: cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_DOCUMENT_FORMATS}) or use one of the explicit '<source>-to-<target>' commands\n`);
 		return 2;
 	}
-	const target = resolveGenericTarget(output, options);
+	const target = resolveTargetFormat(output, options.out, options.to);
 	if ("errorMessage" in target) {
 		process.stderr.write(`convert: ${target.errorMessage}\n`);
 		return 2;
@@ -222,6 +264,7 @@ function registerConversionCommands(program) {
 		const command = program.command(`${commandName} <input> [output]`).description(`convert a ${source} document to ${target}`);
 		addConversionFlags(command);
 		addDumpPackageOption(command);
+		if (target === "pdf") addFontOptions(command);
 		command.action(async (input, output, options) => {
 			process.exitCode = await buildConversionAction(source, target)(input, output, toConversionCommandOptions(options));
 		});
@@ -229,14 +272,15 @@ function registerConversionCommands(program) {
 	const generic = program.command("convert <input> [output]").description("convert between any two supported document formats, inferring source/target from file extensions where possible");
 	addConversionFlags(generic);
 	addDumpPackageOption(generic);
-	generic.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_FORMATS})`);
+	addFontOptions(generic);
+	generic.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_DOCUMENT_FORMATS})`);
 	generic.action(async (input, output, options) => {
 		process.exitCode = await runGenericConvert(input, output, options);
 	});
 }
 //#endregion
 //#region src/commands/formats.ts
-const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, pdf-inspect";
+const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, pdf-inspect, from-package";
 function registerFormatsCommand(program) {
 	program.command("formats").description("list every source -> target conversion this CLI supports via a <source>-to-<target> command").option("--json", "emit the conversion list as a JSON array instead of a human-readable table", false).action((options) => {
 		const { conversions } = createLocalDocumentConverter();
@@ -249,6 +293,86 @@ function registerFormatsCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/from-package.ts
+function buildBytesForTarget(pkg, target) {
+	if (target === "pdf") {
+		if (pkg.layout === void 0) throw new Error("this DocumentPackage has no layout -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries one; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		return writePdf(pkg.layout);
+	}
+	switch (target) {
+		case "docx": return encodePackage(buildDocxPackage(pkg.content));
+		case "pptx": return encodePackage(buildPptxPackage(pkg.content));
+		case "odt": return encodePackage$1(buildOdtPackage(pkg.content));
+		case "odp": return encodePackage$1(buildOdpPackage(pkg.content));
+		case "ods": return encodePackage$1(buildOdsPackage(pkg.content));
+		case "odg": return encodePackage$1(buildOdgPackage(pkg.content));
+		case "markdown": return encodeMarkdownText(buildMarkdownText(pkg.content));
+		case "xlsx": throw new Error("'xlsx' cannot be built from a DocumentPackage directly -- documents.js does not re-export a ContentDocument-to-xlsx builder; convert to 'ods' here, then run 'ods-to-xlsx' on the result instead");
+		case "odf": throw new Error("'odf' (a standalone formula document) cannot be built from a DocumentPackage -- there is no ContentDocument-to-odf builder");
+	}
+}
+async function runFromPackage(input, output, options) {
+	const command = "from-package";
+	if (output !== void 0 && options.out !== void 0 && output !== options.out) {
+		process.stderr.write(`[${command}] conflicting output destinations: positional '${output}' and --out '${options.out}'\n`);
+		return 2;
+	}
+	const target = resolveTargetFormat(output, options.out, options.to);
+	if ("errorMessage" in target) {
+		process.stderr.write(`[${command}] ${target.errorMessage}\n`);
+		return 2;
+	}
+	const resolvedOutput = output ?? options.out ?? (input === "-" ? "-" : resolveDefaultOutputPath(input, target.format));
+	const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeout });
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(inputBytes);
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			process.stderr.write(`[${command}] '${input}' is not valid JSON: ${error instanceof Error ? error.message : String(error)}\n`);
+			return 1;
+		}
+		const result = documentFromJson(parsed);
+		if (result.kind !== "DocumentPackage") {
+			process.stderr.write(`[${command}] '${input}' is a ${result.kind}, not a DocumentPackage -- only a file written by --dump-package can be read back by this command\n`);
+			return 2;
+		}
+		const bytes = buildBytesForTarget(result.value, target.format);
+		await writeOutput(resolvedOutput, bytes);
+		createDiagnosticReporter({
+			json: options.json,
+			quiet: options.quiet,
+			command
+		}).summarize({
+			output: resolvedOutput,
+			bytes: bytes.byteLength,
+			diagnosticCount: 0
+		});
+		return 0;
+	} catch (error) {
+		if (error instanceof UnrecognizedDocumentSchemaError) {
+			process.stderr.write(`[${command}] '${input}' has no recognised $schema -- only a file written by --dump-package can be read back by this command\n`);
+			return 1;
+		}
+		process.stderr.write(`${formatError(error, options.verbose)}\n`);
+		return mapErrorToExit(error, getAbortReason());
+	}
+}
+function registerFromPackageCommand(program) {
+	const command = program.command("from-package <input> [output]").description("read a DocumentPackage previously written by --dump-package and export it to a real target format");
+	addOutOption(command);
+	addTimeoutOption(command);
+	addJsonOption(command);
+	addQuietOption(command);
+	addVerboseOption(command);
+	command.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_DOCUMENT_FORMATS})`);
+	command.action(async (input, output, options) => {
+		process.exitCode = await runFromPackage(input, output, options);
+	});
+}
+//#endregion
 //#region src/commands/odb.ts
 function reportOdbError(command, error, verbose, abortReason) {
 	if (error instanceof OdbNoEmbeddedDataSourceError || error instanceof OdbUnsupportedFormatError) {
@@ -350,6 +474,52 @@ async function runOdbTables(input, options) {
 		return reportOdbError(command, error, false, getAbortReason());
 	}
 }
+async function runOdbForms(input, options) {
+	const command = "odb-forms";
+	const { signal, getAbortReason } = createRuntimeSignal({});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const forms = readOdbForms(decodePackage(new Uint8Array(inputBytes)));
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(forms.map((form) => odbFormSummary(form)))}\n`);
+			return 0;
+		}
+		if (forms.length === 0) {
+			process.stdout.write("This database declares no forms.\n");
+			return 0;
+		}
+		for (const form of forms) {
+			process.stdout.write(`${describeOdbForm(form)}\n`);
+			for (const line of formatOdbFormLines(form)) process.stdout.write(`  ${line}\n`);
+		}
+		return 0;
+	} catch (error) {
+		return reportOdbError(command, error, false, getAbortReason());
+	}
+}
+async function runOdbReports(input, options) {
+	const command = "odb-reports";
+	const { signal, getAbortReason } = createRuntimeSignal({});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const reports = readOdbReports(decodePackage(new Uint8Array(inputBytes)));
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(reports)}\n`);
+			return 0;
+		}
+		if (reports.length === 0) {
+			process.stdout.write("This database declares no reports.\n");
+			return 0;
+		}
+		for (const report of reports) {
+			process.stdout.write(`${describeOdbReport(report)}\n`);
+			for (const line of formatOdbReportLines(report)) process.stdout.write(`  ${line}\n`);
+		}
+		return 0;
+	} catch (error) {
+		return reportOdbError(command, error, false, getAbortReason());
+	}
+}
 function registerOdbToXlsxCommand(program) {
 	const command = program.command("odb-to-xlsx <input> [output]").description("extract every table an embedded .odb database declares into one xlsx workbook, one sheet per table");
 	addOutOption(command);
@@ -378,10 +548,22 @@ function registerOdbTablesCommand(program) {
 		process.exitCode = await runOdbTables(input, options);
 	});
 }
+function registerOdbFormsCommand(program) {
+	program.command("odb-forms <input>").description("list every form an .odb declares, with each form's own data source and its field-bound controls").option("--json", "emit the form structure as a JSON array instead of a human-readable report", false).action(async (input, options) => {
+		process.exitCode = await runOdbForms(input, options);
+	});
+}
+function registerOdbReportsCommand(program) {
+	program.command("odb-reports <input>").description("list every report an .odb declares, with each report's own data-source command, band/group structure, and rpt: formula expressions").option("--json", "emit the report structure as a JSON array instead of a human-readable report", false).action(async (input, options) => {
+		process.exitCode = await runOdbReports(input, options);
+	});
+}
 function registerOdbCommands(program) {
 	registerOdbToXlsxCommand(program);
 	registerOdbToCsvCommand(program);
 	registerOdbTablesCommand(program);
+	registerOdbFormsCommand(program);
+	registerOdbReportsCommand(program);
 }
 //#endregion
 //#region src/commands/odm.ts
@@ -417,11 +599,26 @@ async function runOdmToPdf(input, output, options) {
 		command
 	});
 	let diagnosticCount = 0;
+	const reportFontSubstitution = options.reportFontSubstitutions === true ? createFontSubstitutionReporter({
+		json: options.json,
+		quiet: options.quiet,
+		command
+	}) : void 0;
 	try {
 		const inputBytes = await readInput(input, { signal });
+		const fonts = await loadProvidedFonts(options.fontFile ?? [], { signal });
 		const bytes = odmToPdf(new Uint8Array(inputBytes), {
 			signal,
 			resolveSubDocument,
+			fonts,
+			onFontSubstitution: (substitution) => {
+				if (reportFontSubstitution !== void 0) {
+					reportFontSubstitution(substitution);
+					return;
+				}
+				diagnosticCount += 1;
+				reporter.report(fontSubstitutionToDiagnostic(substitution));
+			},
 			onSubstitution: (substitution, context) => {
 				diagnosticCount += 1;
 				reporter.report(substitutionToDiagnostic(substitution, context.pageIndex));
@@ -450,6 +647,7 @@ function registerOdmCommand(program) {
 	addJsonOption(command);
 	addQuietOption(command);
 	addVerboseOption(command);
+	addFontOptions(command);
 	command.option("--chapters-dir <dir>", "directory to search for each unresolved chapter href, matched by the href's own basename");
 	command.option("--chapter <href>=<file>", "resolve one chapter href to a local file explicitly; repeatable", collectChapterOverride, /* @__PURE__ */ new Map());
 	command.action(async (input, output, options) => {
@@ -546,7 +744,7 @@ function registerPdfInspectCommand(program) {
 }
 //#endregion
 //#region package.json
-var version = "1.1.0";
+var version = "1.2.0";
 //#endregion
 //#region src/program.ts
 function createProgram() {
@@ -559,6 +757,7 @@ function createProgram() {
 	});
 	registerConversionCommands(program);
 	registerFormatsCommand(program);
+	registerFromPackageCommand(program);
 	registerOdmCommand(program);
 	registerOdbCommands(program);
 	registerPdfInspectCommand(program);
@@ -568,7 +767,7 @@ function createProgram() {
 //#region src/cli.ts
 async function launchTui(startPath, signal) {
 	try {
-		const { runTui } = await import("./tui-Dywpifqx.js");
+		const { runTui } = await import("./tui-DD4bQp39.js");
 		await runTui({
 			startPath,
 			signal