@json-to-office/jto-ops 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { FontRuntimeOpts, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, ResolvedFont } from '@json-to-office/shared';
+import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis } from '@json-to-office/quality';
 
 type FormatName = 'docx' | 'pptx';
 interface GeneratorOptions {
@@ -37,6 +38,13 @@ interface GeneratorOptions {
      * `GeneratorResult` — allocate one array per logical request.
      */
     warnings?: GenerationWarning[];
+    /** Design profile and invocation-specific enforcement. */
+    quality?: {
+        profile?: QualityProfile;
+        policy?: QualityPolicy;
+    };
+    /** Opaque canonical prologue output shared by analysis and rendering. */
+    prepared?: PreparedDocument;
 }
 interface GeneratorResult {
     generateBuffer: (document: any) => Promise<Buffer>;
@@ -67,8 +75,14 @@ interface FormatAdapter {
         valid: boolean;
         errors?: any[];
     };
+    /** Analyze format-specific design quality with profiles, policy, and gate. */
+    analyzeQuality?(doc: unknown, options?: GeneratorOptions): Promise<QualityAnalysis>;
+    /** Prepare effective values and provenance once for official pipelines. */
+    prepareDocument?(doc: unknown, options?: GeneratorOptions): Promise<PreparedDocument>;
     generateSchema(options?: any): any;
     getBuiltinThemes(): Record<string, any>;
+    /** Full values for ESM hosts; falls back to `getBuiltinThemes` for plugins. */
+    getBuiltinThemeValues?(): Promise<Record<string, any>>;
     resolveTheme(options: GeneratorOptions): Promise<any>;
     loadCustomThemes(options: GeneratorOptions): Promise<Record<string, any> | undefined>;
     /**
@@ -107,8 +121,13 @@ declare class DocxFormatAdapter implements FormatAdapter {
         valid: boolean;
         errors?: any[];
     };
+    analyzeQuality(doc: unknown, options?: GeneratorOptions): Promise<QualityAnalysis>;
+    prepareDocument(doc: unknown, options?: GeneratorOptions): Promise<PreparedDocument>;
+    /** Prepare into a caller-owned sink; `prepareDocument` owns the reporting. */
+    private prepareModel;
     generateSchema(_options?: any): any;
     getBuiltinThemes(): Record<string, any>;
+    getBuiltinThemeValues(): Promise<Record<string, any>>;
     resolveTheme(options: GeneratorOptions): Promise<any>;
     /**
      * Resolve `theme`/`themePath` once for a whole run: `themePath` is read a
@@ -134,8 +153,13 @@ declare class PptxFormatAdapter implements FormatAdapter {
         valid: boolean;
         errors?: any[];
     };
+    analyzeQuality(doc: unknown, options?: GeneratorOptions): Promise<QualityAnalysis>;
+    prepareDocument(doc: unknown, options?: GeneratorOptions): Promise<PreparedDocument>;
+    /** Prepare into a caller-owned sink; `prepareDocument` owns the reporting. */
+    private prepareModel;
     generateSchema(_options?: any): any;
     getBuiltinThemes(): Record<string, any>;
+    getBuiltinThemeValues(): Promise<Record<string, any>>;
     resolveTheme(options: GeneratorOptions): Promise<any>;
     /**
      * Resolve `theme`/`themePath` once for a whole run: `themePath` is read a
@@ -230,6 +254,55 @@ declare function createLibreOfficePptxBatchRasterizer(options?: {
     cacheDir?: string | null;
 }): PptxBatchRasterizer;
 
+/**
+ * Text geometry from a rendered PDF — the ground truth the quality
+ * estimators are guessing at (#216 follow-up).
+ *
+ * The pptx preview pipeline already produces a PDF (soffice → pdftoppm) and
+ * uses it purely as a bitmap source. That PDF records the exact position of
+ * every glyph as laid out by LibreOffice — the same engine the quality rules
+ * try to predict. `pdftotext -bbox` (poppler, already a rasterizer
+ * dependency alongside pdftoppm) dumps per-word bounding boxes; this module
+ * parses them into slide-space points so callers can compare a rule's
+ * estimate against what the renderer actually did.
+ *
+ * Coordinates: PDF points (1/72 in), origin at the page's top-left corner,
+ * y increasing downward — the same frame as authored inches × 72. A PDF page
+ * rendered from a slide has the slide's dimensions, so word boxes compare
+ * directly against authored shape geometry with no transform.
+ *
+ * Consumers: the quality ground-truth harness (estimator calibration) today;
+ * a `rendered`-certainty analysis pass tomorrow.
+ */
+/** One word as laid out on the page, in PDF points, top-left origin. */
+interface PdfTextWord {
+    text: string;
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+/** One PDF page: its size in points plus every word poppler segmented. */
+interface PdfTextPage {
+    widthPt: number;
+    heightPt: number;
+    words: PdfTextWord[];
+}
+/**
+ * Parse `pdftotext -bbox` output (XHTML with `<page>`/`<word>` elements).
+ * Pure — feed it a captured document for tests, or the runner's stdout.
+ */
+declare function parsePdfTextBbox(bboxXml: string): PdfTextPage[];
+/** True when a `pdftotext` binary is reachable — lets harnesses skip early. */
+declare function pdftotextAvailable(): Promise<boolean>;
+/**
+ * Extract per-word text geometry from a PDF on disk. One pdftotext spawn,
+ * output streamed through stdout — nothing else touches the filesystem.
+ */
+declare function extractPdfTextGeometry(pdfPath: string, options?: {
+    timeoutMs?: number;
+}): Promise<PdfTextPage[]>;
+
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
  * duration of one PDF conversion, then clean up.
@@ -421,4 +494,4 @@ declare function emitDiagnostic(text: string, tone?: DiagnosticTone): void;
  */
 declare const stderrDiagnosticSink: DiagnosticSink;
 
-export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, MacOSCoreTextStager, NoopFontStager, PptxFormatAdapter, type RasterizerCacheStats, WindowsFontStager, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, getFontStager, getRasterizerCacheStats, runWithDiagnosticSink, stderrDiagnosticSink };
+export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, MacOSCoreTextStager, NoopFontStager, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, type RasterizerCacheStats, WindowsFontStager, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, extractPdfTextGeometry, getFontStager, getRasterizerCacheStats, parsePdfTextBbox, pdftotextAvailable, runWithDiagnosticSink, stderrDiagnosticSink };

package/dist/index.js

@@ -892,6 +892,36 @@ function toGenerationWarnings(raw) {
     }
   }));
 }
+function preparedThemeLabel(prepared) {
+  const label = prepared.metadata?.themeLabel;
+  return typeof label === "string" ? label : void 0;
+}
+var PREPARED_SOURCE = Symbol("jto.prepared.source");
+var PREPARED_WARNINGS = Symbol("jto.prepared.warnings");
+function stampPrepared(prepared, source, warnings) {
+  return Object.assign(prepared, {
+    [PREPARED_SOURCE]: source,
+    [PREPARED_WARNINGS]: warnings
+  });
+}
+function preparedFor(prepared, document) {
+  if (!prepared) return void 0;
+  const source = prepared[PREPARED_SOURCE];
+  return source !== void 0 && source === document ? prepared : void 0;
+}
+function warningKey(warning) {
+  return `${warning.component}|${warning.context?.code ?? ""}|${warning.message}`;
+}
+function withoutPreparedWarnings(warnings, prepared) {
+  const emitted = prepared?.[PREPARED_WARNINGS];
+  if (!emitted || emitted.length === 0) return warnings;
+  const seen = new Set(emitted.map(warningKey));
+  return warnings.filter((warning) => !seen.has(warningKey(warning)));
+}
+function documentRenderer(document) {
+  const renderer = document?.renderer;
+  return typeof renderer === "string" ? renderer : void 0;
+}
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 function safeThemeKey(name) {
   return name && !UNSAFE_KEYS.has(name) ? name : "custom";
@@ -967,12 +997,24 @@ var DocxFormatAdapter = class {
   async generateBuffer(json, options) {
     const core = await import("@json-to-office/core-docx");
     const parsed = typeof json === "string" ? JSON.parse(json) : json;
-    const resolved = await this.resolveThemes(options);
-    const { document: docDefinition, customThemes } = withRequestedTheme(
-      parsed,
-      resolved.requested,
-      resolved.customThemes
+    const prepared = preparedFor(
+      options.prepared?.format === "docx" ? options.prepared : void 0,
+      parsed
     );
+    let docDefinition;
+    let customThemes;
+    if (prepared) {
+      docDefinition = prepared.model.authored;
+    } else {
+      const resolved = await this.resolveThemes(options);
+      const normalized = withRequestedTheme(
+        parsed,
+        resolved.requested,
+        resolved.customThemes
+      );
+      docDefinition = normalized.document;
+      customThemes = normalized.customThemes;
+    }
     const services = buildDocxServices();
     const warnings = [];
     const buffer = await core.generateBufferFromJson(docDefinition, {
@@ -986,10 +1028,12 @@ var DocxFormatAdapter = class {
       generatedAt: options.generatedAt,
       baseDir: options.baseDir,
       renderer: options.renderer,
+      prepared,
       warnings
     });
-    emitGenerationWarnings(warnings);
-    options.warnings?.push(...toGenerationWarnings(warnings));
+    const emitted = withoutPreparedWarnings(warnings, prepared);
+    emitGenerationWarnings(emitted);
+    options.warnings?.push(...toGenerationWarnings(emitted));
     return buffer;
   }
   async createGenerator(plugins, options) {
@@ -997,32 +1041,45 @@ var DocxFormatAdapter = class {
     const hasPlugins = plugins.length > 0;
     const pluginNames = plugins.map((p) => p.name);
     const services = buildDocxServices();
-    const {
-      requested: requestedTheme,
-      customThemes,
-      label: themeLabel
-    } = await this.resolveThemes(options);
+    const prepared = !hasPlugins && options.prepared?.format === "docx" ? options.prepared : void 0;
+    const resolved = prepared ? void 0 : await this.resolveThemes(options);
+    const requestedTheme = resolved?.requested;
+    const customThemes = resolved?.customThemes;
+    const themeLabel = prepared ? preparedThemeLabel(prepared) : resolved?.label;
     if (!hasPlugins) {
+      let fallbackThemes;
+      const themesFor = () => fallbackThemes ??= resolved ? Promise.resolve(resolved) : this.resolveThemes(options);
       return {
         generateBuffer: async (document) => {
           const parsed = typeof document === "string" ? JSON.parse(document) : document;
-          const { document: docDefinition, customThemes: themes } = withRequestedTheme(parsed, requestedTheme, customThemes);
+          const usable = preparedFor(prepared, parsed);
+          const themes = usable ? void 0 : await themesFor();
+          const normalized = usable ? { document: usable.model.authored, customThemes: void 0 } : withRequestedTheme(
+            parsed,
+            themes?.requested,
+            themes?.customThemes
+          );
           const warnings = [];
-          const buffer = await core.generateBufferFromJson(docDefinition, {
-            customThemes: themes,
-            services,
-            fonts: options.fonts,
-            validation: {
-              allowUnknownFields: options.validation?.allowUnknownFields
-            },
-            deterministic: options.deterministic,
-            generatedAt: options.generatedAt,
-            baseDir: options.baseDir,
-            renderer: options.renderer,
-            warnings
-          });
-          emitGenerationWarnings(warnings);
-          options.warnings?.push(...toGenerationWarnings(warnings));
+          const buffer = await core.generateBufferFromJson(
+            normalized.document,
+            {
+              customThemes: normalized.customThemes,
+              services,
+              fonts: options.fonts,
+              validation: {
+                allowUnknownFields: options.validation?.allowUnknownFields
+              },
+              deterministic: options.deterministic,
+              generatedAt: options.generatedAt,
+              baseDir: options.baseDir,
+              renderer: options.renderer,
+              prepared: usable,
+              warnings
+            }
+          );
+          const emitted = withoutPreparedWarnings(warnings, usable);
+          emitGenerationWarnings(emitted);
+          options.warnings?.push(...toGenerationWarnings(emitted));
           return buffer;
         },
         hasPlugins: false,
@@ -1104,6 +1161,64 @@ var DocxFormatAdapter = class {
       ...result.errors.length > 0 && { errors: result.errors }
     };
   }
+  async analyzeQuality(doc, options = {}) {
+    const core = await import("@json-to-office/core-docx");
+    const parsed = typeof doc === "string" ? JSON.parse(doc) : doc;
+    let prepared = preparedFor(
+      options.prepared?.format === "docx" ? options.prepared : void 0,
+      parsed
+    );
+    if (!prepared) {
+      try {
+        prepared = await this.prepareModel(parsed, options, []);
+      } catch {
+      }
+    }
+    return core.analyzeDocxQuality(prepared?.model.authored ?? parsed, {
+      ...prepared && { prepared },
+      renderer: options.renderer ?? documentRenderer(parsed),
+      profile: options.quality?.profile,
+      policy: options.quality?.policy
+    });
+  }
+  async prepareDocument(doc, options = {}) {
+    const warnings = [];
+    const prepared = await this.prepareModel(doc, options, warnings);
+    emitGenerationWarnings(warnings);
+    options.warnings?.push(...toGenerationWarnings(warnings));
+    return prepared;
+  }
+  /** Prepare into a caller-owned sink; `prepareDocument` owns the reporting. */
+  async prepareModel(doc, options, warnings) {
+    const core = await import("@json-to-office/core-docx");
+    const parsed = typeof doc === "string" ? JSON.parse(doc) : doc;
+    const resolved = await this.resolveThemes(options);
+    const normalized = withRequestedTheme(
+      parsed,
+      resolved.requested,
+      resolved.customThemes
+    );
+    const prepared = core.prepareDocxQualityDocument(
+      normalized.document,
+      {
+        customThemes: normalized.customThemes,
+        fonts: options.fonts,
+        renderer: options.renderer ?? documentRenderer(parsed),
+        warnings
+      }
+    );
+    return stampPrepared(
+      {
+        ...prepared,
+        metadata: {
+          ...prepared.metadata,
+          ...resolved.label && { themeLabel: resolved.label }
+        }
+      },
+      parsed,
+      toGenerationWarnings(warnings)
+    );
+  }
   generateSchema(_options) {
     return null;
   }
@@ -1115,6 +1230,10 @@ var DocxFormatAdapter = class {
       return {};
     }
   }
+  async getBuiltinThemeValues() {
+    const core = await import("@json-to-office/core-docx");
+    return core.themes || {};
+  }
   async resolveTheme(options) {
     const core = await import("@json-to-office/core-docx");
     const { requested } = await this.resolveThemes(options);
@@ -1227,12 +1346,24 @@ var PptxFormatAdapter = class {
   async generateBuffer(json, options) {
     const core = await import("@json-to-office/core-pptx");
     const parsed = typeof json === "string" ? JSON.parse(json) : json;
-    const resolved = await this.resolveThemes(options);
-    const { document: docDefinition, customThemes } = withRequestedTheme(
-      parsed,
-      resolved.requested,
-      resolved.customThemes
+    const prepared = preparedFor(
+      options.prepared?.format === "pptx" ? options.prepared : void 0,
+      parsed
     );
+    let docDefinition;
+    let customThemes;
+    if (prepared) {
+      docDefinition = prepared.model.authored;
+    } else {
+      const resolved = await this.resolveThemes(options);
+      const normalized = withRequestedTheme(
+        parsed,
+        resolved.requested,
+        resolved.customThemes
+      );
+      docDefinition = normalized.document;
+      customThemes = normalized.customThemes;
+    }
     const services = buildServicesFromEnv();
     const result = await core.generateBufferWithWarnings(docDefinition, {
       customThemes,
@@ -1244,11 +1375,15 @@ var PptxFormatAdapter = class {
       deterministic: options.deterministic,
       generatedAt: options.generatedAt,
       baseDir: options.baseDir,
-      renderer: options.renderer
+      renderer: options.renderer,
+      prepared
     });
-    const normalized = toGenerationWarnings(result.warnings);
-    emitGenerationWarnings(normalized);
-    options.warnings?.push(...normalized);
+    const emitted = withoutPreparedWarnings(
+      toGenerationWarnings(result.warnings),
+      prepared
+    );
+    emitGenerationWarnings(emitted);
+    options.warnings?.push(...emitted);
     return result.buffer;
   }
   async createGenerator(plugins, options) {
@@ -1256,31 +1391,46 @@ var PptxFormatAdapter = class {
     const hasPlugins = plugins.length > 0;
     const pluginNames = plugins.map((p) => p.name);
     const services = buildServicesFromEnv();
-    const {
-      requested: requestedTheme,
-      customThemes,
-      label: themeLabel
-    } = await this.resolveThemes(options);
+    const prepared = !hasPlugins && options.prepared?.format === "pptx" ? options.prepared : void 0;
+    const resolved = prepared ? void 0 : await this.resolveThemes(options);
+    const requestedTheme = resolved?.requested;
+    const customThemes = resolved?.customThemes;
+    const themeLabel = prepared ? preparedThemeLabel(prepared) : resolved?.label;
     if (!hasPlugins) {
+      let fallbackThemes;
+      const themesFor = () => fallbackThemes ??= resolved ? Promise.resolve(resolved) : this.resolveThemes(options);
       return {
         generateBuffer: async (document) => {
           const parsed = typeof document === "string" ? JSON.parse(document) : document;
-          const { document: docDefinition, customThemes: themes } = withRequestedTheme(parsed, requestedTheme, customThemes);
-          const result = await core.generateBufferWithWarnings(docDefinition, {
-            customThemes: themes,
-            services,
-            fonts: options.fonts,
-            validation: {
-              allowUnknownFields: options.validation?.allowUnknownFields
-            },
-            deterministic: options.deterministic,
-            generatedAt: options.generatedAt,
-            baseDir: options.baseDir,
-            renderer: options.renderer
-          });
-          const normalized = toGenerationWarnings(result.warnings);
-          emitGenerationWarnings(normalized);
-          options.warnings?.push(...normalized);
+          const usable = preparedFor(prepared, parsed);
+          const themes = usable ? void 0 : await themesFor();
+          const normalized = usable ? { document: usable.model.authored, customThemes: void 0 } : withRequestedTheme(
+            parsed,
+            themes?.requested,
+            themes?.customThemes
+          );
+          const result = await core.generateBufferWithWarnings(
+            normalized.document,
+            {
+              customThemes: normalized.customThemes,
+              services,
+              fonts: options.fonts,
+              validation: {
+                allowUnknownFields: options.validation?.allowUnknownFields
+              },
+              deterministic: options.deterministic,
+              generatedAt: options.generatedAt,
+              baseDir: options.baseDir,
+              renderer: options.renderer,
+              prepared: usable
+            }
+          );
+          const warnings = withoutPreparedWarnings(
+            toGenerationWarnings(result.warnings),
+            usable
+          );
+          emitGenerationWarnings(warnings);
+          options.warnings?.push(...warnings);
           return result.buffer;
         },
         hasPlugins: false,
@@ -1345,6 +1495,66 @@ var PptxFormatAdapter = class {
       ...result.errors.length > 0 && { errors: result.errors }
     };
   }
+  async analyzeQuality(doc, options = {}) {
+    const core = await import("@json-to-office/core-pptx");
+    const parsed = typeof doc === "string" ? JSON.parse(doc) : doc;
+    let prepared = preparedFor(
+      options.prepared?.format === "pptx" ? options.prepared : void 0,
+      parsed
+    );
+    if (!prepared) {
+      try {
+        prepared = await this.prepareModel(parsed, options, []);
+      } catch {
+      }
+    }
+    return core.analyzePptxQuality(prepared?.model.authored ?? parsed, {
+      ...prepared && { prepared },
+      renderer: options.renderer ?? documentRenderer(parsed),
+      profile: options.quality?.profile,
+      policy: options.quality?.policy
+    });
+  }
+  async prepareDocument(doc, options = {}) {
+    const warnings = [];
+    const prepared = await this.prepareModel(doc, options, warnings);
+    const normalized = toGenerationWarnings(warnings);
+    emitGenerationWarnings(normalized);
+    options.warnings?.push(...normalized);
+    return prepared;
+  }
+  /** Prepare into a caller-owned sink; `prepareDocument` owns the reporting. */
+  async prepareModel(doc, options, warnings) {
+    const core = await import("@json-to-office/core-pptx");
+    const parsed = typeof doc === "string" ? JSON.parse(doc) : doc;
+    const resolved = await this.resolveThemes(options);
+    const normalized = withRequestedTheme(
+      parsed,
+      resolved.requested,
+      resolved.customThemes
+    );
+    const prepared = core.preparePptxQualityDocument(
+      normalized.document,
+      {
+        customThemes: normalized.customThemes,
+        fonts: options.fonts,
+        services: buildServicesFromEnv(),
+        renderer: options.renderer ?? documentRenderer(parsed),
+        warnings
+      }
+    );
+    return stampPrepared(
+      {
+        ...prepared,
+        metadata: {
+          ...prepared.metadata,
+          ...resolved.label && { themeLabel: resolved.label }
+        }
+      },
+      parsed,
+      toGenerationWarnings(warnings)
+    );
+  }
   generateSchema(_options) {
     return null;
   }
@@ -1356,6 +1566,10 @@ var PptxFormatAdapter = class {
       return {};
     }
   }
+  async getBuiltinThemeValues() {
+    const core = await import("@json-to-office/core-pptx");
+    return core.pptxThemes || {};
+  }
   async resolveTheme(options) {
     const core = await import("@json-to-office/core-pptx");
     const themes = core.pptxThemes || {};
@@ -1448,6 +1662,116 @@ function createAdapter(format) {
       throw new Error(`Unknown format: ${format}`);
   }
 }
+
+// src/pdf-text-geometry.ts
+import { execFile as execFile2 } from "child_process";
+import * as path6 from "path";
+var ENTITIES = {
+  "&": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&apos;": "'",
+  "&#34;": '"',
+  "&#39;": "'"
+};
+function decodeEntities(value) {
+  return value.replace(
+    /&(?:amp|lt|gt|quot|apos|#34|#39);/g,
+    (entity) => ENTITIES[entity] ?? entity
+  );
+}
+var PAGE_PATTERN = /<page\s+width="([\d.]+)"\s+height="([\d.]+)">([\s\S]*?)<\/page>/g;
+var WORD_PATTERN = /<word\s+xMin="(-?[\d.]+)"\s+yMin="(-?[\d.]+)"\s+xMax="(-?[\d.]+)"\s+yMax="(-?[\d.]+)">([\s\S]*?)<\/word>/g;
+function parsePdfTextBbox(bboxXml) {
+  const pages = [];
+  for (const pageMatch of bboxXml.matchAll(PAGE_PATTERN)) {
+    const words = [];
+    for (const wordMatch of pageMatch[3].matchAll(WORD_PATTERN)) {
+      words.push({
+        xMin: Number(wordMatch[1]),
+        yMin: Number(wordMatch[2]),
+        xMax: Number(wordMatch[3]),
+        yMax: Number(wordMatch[4]),
+        text: decodeEntities(wordMatch[5])
+      });
+    }
+    pages.push({
+      widthPt: Number(pageMatch[1]),
+      heightPt: Number(pageMatch[2]),
+      words
+    });
+  }
+  return pages;
+}
+function pdftotextCandidates() {
+  const candidates = [];
+  const configured = process.env.PDFTOTEXT_PATH?.trim();
+  if (configured) candidates.push(configured);
+  candidates.push("pdftotext");
+  return [...new Set(candidates)];
+}
+async function run(binary, args, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    execFile2(
+      binary,
+      args,
+      { timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
+      (error, stdout) => {
+        if (error) reject(error);
+        else resolve2(stdout);
+      }
+    );
+  });
+}
+var pdftotextPromise;
+async function resolvePdftotext() {
+  if (!pdftotextPromise) {
+    pdftotextPromise = (async () => {
+      for (const candidate of pdftotextCandidates()) {
+        if (candidate.includes(path6.sep)) {
+          try {
+            await run(candidate, ["-v"], 1e4);
+            return candidate;
+          } catch {
+            continue;
+          }
+        }
+        try {
+          await run(candidate, ["-v"], 1e4);
+          return candidate;
+        } catch (error) {
+          const code = error.code;
+          if (code !== "ENOENT" && code !== "EACCES") return candidate;
+        }
+      }
+      throw new Error(
+        `Text geometry extraction needs pdftotext (poppler), which was not found. Install poppler-utils or set PDFTOTEXT_PATH (searched: ${pdftotextCandidates().join(", ")}).`
+      );
+    })().catch((error) => {
+      pdftotextPromise = void 0;
+      throw error;
+    });
+  }
+  return pdftotextPromise;
+}
+async function pdftotextAvailable() {
+  try {
+    await resolvePdftotext();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function extractPdfTextGeometry(pdfPath, options = {}) {
+  const binary = await resolvePdftotext();
+  const stdout = await run(
+    binary,
+    ["-bbox", pdfPath, "-"],
+    options.timeoutMs ?? 6e4
+  );
+  return parsePdfTextBbox(stdout);
+}
 export {
   DocxFormatAdapter,
   FontconfigStager,
@@ -1460,8 +1784,11 @@ export {
   createLibreOfficePptxBatchRasterizer,
   createLibreOfficePptxRasterizer,
   emitDiagnostic,
+  extractPdfTextGeometry,
   getFontStager,
   getRasterizerCacheStats,
+  parsePdfTextBbox,
+  pdftotextAvailable,
   runWithDiagnosticSink,
   stderrDiagnosticSink
 };