@json-to-office/jto-ops 1.4.0 → 1.11.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 {
@@ -26,6 +27,14 @@ interface GeneratorOptions {
      * Undefined means the format's default (`docxjs` / `pptxgenjs`).
      */
     renderer?: string;
+    /**
+     * Rasterize a PNG fallback for each inline SVG. Defaults to true.
+     *
+     * DOCX only — pptx embeds SVG without a raster twin. Only readers older than
+     * Word 2016 draw it, and producing it dominates the render of a document
+     * whose artwork is many small SVGs.
+     */
+    svgRasterFallback?: boolean;
     /**
      * Optional sink for structured generation warnings (FONT_UNRESOLVED and
      * friends). Mirrors core-docx's `JsonGenerationOptions.warnings`, and is the
@@ -37,6 +46,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 +83,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 +129,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 +161,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 +262,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 +502,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 };