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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { FontRuntimeOpts, GenerationWarning, PptxBatchRasterizer, PptxRasterizer, ResolvedFont } from '@json-to-office/shared';
+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>;
     /**
@@ -78,6 +92,16 @@ interface FormatAdapter {
      * list is read from it rather than repeated here, so the two cannot drift.
      */
     rendererIds(): Promise<readonly string[]>;
+    /**
+     * The same renderers, each with whether its backend loads on this host.
+     *
+     * `rendererIds` answers "what is registered", which is not the same question:
+     * a factory only runs when its renderer is selected, so an id says nothing
+     * about whether the render behind it will work. Anything that *advertises*
+     * renderers should report this instead — otherwise a caller picks one, gets
+     * a green light from validation, and fails a call later.
+     */
+    rendererStatuses(): Promise<readonly RendererStatus[]>;
     /** Cumulative visual pre-pass dedupe counters (DOCX only) (#156). */
     getVisualPrepassStats?(): Promise<any>;
     /** Reset per-format cache observability counters (DOCX only). */
@@ -89,6 +113,7 @@ declare class DocxFormatAdapter implements FormatAdapter {
     label: string;
     defaultPort: number;
     rendererIds(): Promise<readonly string[]>;
+    rendererStatuses(): Promise<readonly RendererStatus[]>;
     generateBuffer(json: unknown, options: GeneratorOptions): Promise<Buffer>;
     createGenerator(plugins: any[], options: GeneratorOptions): Promise<GeneratorResult>;
     parseJson(input: string | object): unknown;
@@ -96,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
@@ -115,6 +145,7 @@ declare class PptxFormatAdapter implements FormatAdapter {
     label: string;
     defaultPort: number;
     rendererIds(): Promise<readonly string[]>;
+    rendererStatuses(): Promise<readonly RendererStatus[]>;
     generateBuffer(json: unknown, options: GeneratorOptions): Promise<Buffer>;
     createGenerator(plugins: any[], options: GeneratorOptions): Promise<GeneratorResult>;
     parseJson(input: string | object): unknown;
@@ -122,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
@@ -218,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.
@@ -409,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 };