@json-to-office/jto-ops 6.0.0 → 6.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FontRuntimeOpts, ServicesConfig, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, JsonBlockDefinition, BlockSlot, ResolvedFont } from '@json-to-office/shared';
-import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis, QualityRulePack, QualityDiagnostic, QualityAnalyzeOptions } from '@json-to-office/quality';
+import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis, QualityRulePack, QualityDiagnostic, QualityAnalyzeOptions, QualityFact } from '@json-to-office/quality';
 
 type FormatName = 'docx' | 'pptx';
 interface GeneratorOptions {
@@ -469,7 +469,7 @@ declare function extractPdfFonts(pdfPath: string, options?: {
  * pass over it, memoised per fact, so eight rules cost one search.
  */
 
-type RenderedRuleId = 'rendered/clip' | 'rendered/spill' | 'rendered/overlap' | 'rendered/text-missing' | 'rendered/font-substituted' | 'rendered/empty-page' | 'rendered/heading-stranded' | 'rendered/paragraph-split' | 'rendered/page-underfilled';
+type RenderedRuleId = 'rendered/clip' | 'rendered/spill' | 'rendered/overlap' | 'rendered/text-missing' | 'rendered/font-substituted' | 'rendered/empty-page' | 'rendered/heading-stranded' | 'rendered/paragraph-split' | 'rendered/table-split' | 'rendered/page-underfilled';
 declare const RENDERED_QUALITY_RULES: QualityRulePack;
 
 /**
@@ -499,6 +499,9 @@ declare const RENDERED_QUALITY_RULES: QualityRulePack;
  * every occurrence. `assignInventory` resolves them by reading order: the
  * inventory is walked in document order and the stream is in page order, so
  * the next unclaimed occurrence at or after the previous claim is the one.
+ * Where the format knows more before rendering — a slide is its own page,
+ * and its text boxes sit where the deck put them — the entry says so, and
+ * only an occurrence on that page, preferably inside that box, is its own.
  */
 
 /** Fold rendered and authored text into one comparable form. */
@@ -522,6 +525,8 @@ interface OccurrencePart {
 interface TextOccurrence {
     /** Offset into the document stream, for ordering. */
     at: number;
+    /** Offset just past the match: `[at, end)` is the range a claim holds. */
+    end: number;
     /** First and last page the match touches; equal unless it breaks across. */
     pageIndex: number;
     endPageIndex: number;
@@ -541,8 +546,15 @@ interface TextOccurrence {
  * fragment of their row) and the rows stay a line apart. A block reads
  * column by column, so a cell's lines come out together; a row of one
  * fragment outside any block — prose — reads as it lies.
+ *
+ * Rotated text — a chart's value-axis title — has no rows or columns to
+ * take part in. It reads as one run in the order poppler gave it, after the
+ * page's upright text: inside that text it could fall between two lines of
+ * a paragraph and cut it in two, and a slide's takeaway set beside a chart
+ * then reads as clipped, or as never rendered at all. Across a document the
+ * stream sets it after every page (`indexDocument`).
  */
-declare function readingOrder(words: readonly PdfTextWord[]): number[];
+declare function readingOrder(words: readonly PdfTextWord[], lines?: readonly PdfTextLine[]): number[];
 /** What an inventory entry needs to be matched: its text, in reading order. */
 interface InventoryEntry {
     path: string;
@@ -555,6 +567,26 @@ interface InventoryEntry {
      * `missing`, when there is not.
      */
     optional?: boolean;
+    /**
+     * The 0-based page the text is drawn on, when the format knows it before
+     * rendering: a slide is its own page. Only an occurrence starting there
+     * is the entry's — "13 pts" on slide 2 is not "+1.3 pts" on slide 8,
+     * however alike the two fold.
+     */
+    page?: number;
+    /**
+     * Where on that page the text was laid out, in PDF points: a slide text
+     * box. Of the entry's occurrences, one inside this region is its own. A
+     * section tracker that repeats the first word of the title under it is
+     * two occurrences of one word, and reading order cannot say which box
+     * painted which; the boxes can.
+     */
+    region?: {
+        xMin: number;
+        yMin: number;
+        xMax: number;
+        yMax: number;
+    };
 }
 type MappingStatus = 'mapped' | 'ambiguous' | 'missing' | 'skipped';
 interface InventoryMatch<T extends InventoryEntry = InventoryEntry> {
@@ -588,6 +620,13 @@ interface InventoryAssignment<T extends InventoryEntry> {
  * finds the second "Total". An entry with no occurrence is `missing` —
  * fully clipped, or never set — unless it is optional, and one whose every
  * occurrence was already claimed is `ambiguous`.
+ *
+ * A claim holds the whole range it matched, not just where it starts: a
+ * rendered word belongs to one authored string, so "Revenue" inside a title
+ * another entry already owns is not free for a tracker that says "Revenue".
+ * An entry that names its page looks only there, and one that names its
+ * region takes the occurrence lying most inside it before reading order is
+ * consulted at all.
  */
 declare function assignInventory<T extends InventoryEntry>(pages: readonly PdfTextPage[], inventory: readonly T[]): InventoryAssignment<T>;
 
@@ -690,6 +729,30 @@ declare const VISIBLE_SPILL_PT = 2;
  */
 declare function analyzeRenderedDocument(input: RenderedAnalysisInput, options?: QualityAnalyzeOptions): RenderedAnalysis;
 
+/**
+ * The authored side of the rendered pass (#344): the text inventory and the
+ * requested font families, read off a prepared document's quality facts.
+ *
+ * `jto_preview` and the ground-truth harness both hand the pass this, so the
+ * mapping a measurement scores is the mapping the tool ships. Every pointer
+ * in it has already been through the block source maps, and lands on a slot
+ * the author can patch.
+ */
+
+/** The text inventory a format's facts expose, as the analysis reads it. */
+declare function renderedInventoryFromFacts(format: FormatName, facts: readonly QualityFact[]): RenderedTextEntry[];
+/**
+ * Families the pass should find in the PDF: every family the document's
+ * text uses (a `font-family` fact, with its pointer) plus every family the
+ * render resolved from a declared source. A theme family nothing on the page
+ * uses — the default mono face in a report without code — is never embedded
+ * and must not read as substituted.
+ */
+declare function requestedFontsFromFacts(format: FormatName, facts: readonly QualityFact[], resolvedFonts: readonly {
+    family: string;
+    declared: boolean;
+}[]): RequestedFont[];
+
 /**
  * The block boundary matrix (#343, report portion): every JSON block
  * definition a playground template embeds, invoked at the edges of its own
@@ -1003,4 +1066,4 @@ declare function emitDiagnostic(text: string, tone?: DiagnosticTone): void;
  */
 declare const stderrDiagnosticSink: DiagnosticSink;
 
-export { type BlockMatrixCase, type BlockMatrixDefinition, type BlockMatrixOptions, type CaseConditions, type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type ExtractPdfPageInkOptions, FALLBACK_FONTS, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, INK_DPI, INK_THRESHOLD, type InventoryEntry, type InventoryMatch, MATRIX_IMAGE, MacOSCoreTextStager, type MappingStatus, type MatrixCanvas, type MatrixEdge, type MatrixFont, NoopFontStager, type PdfFontInfo, type PdfPageInk, type PdfTextLine, type PdfTextPage, type PdfTextWord, type Pgm, PptxFormatAdapter, RENDERED_QUALITY_RULES, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, type RenderedRuleId, type RenderedTextEntry, type RequestedFont, type TextOccurrence, VISIBLE_SPILL_PT, WindowsFontStager, analyzeRenderedDocument, assignInventory, authoredTextForMatch, blockCaseDocument, boundaryInvocation, boundarySlotValue, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, enumerateBlockDefinitions, extractPdfFonts, extractPdfPageInk, extractPdfTextGeometry, familyRendered, generateBlockMatrix, getFontStager, getRasterizerCacheStats, inkedRows, normalizeForMatch, overBudgetInvocation, pageInkFromPgm, parsePdfFonts, parsePdfTextBbox, parsePgm, pdffontsAvailable, pdftotextAvailable, readingOrder, reportCaseDocument, runWithDiagnosticSink, stderrDiagnosticSink, widestNumber };
+export { type BlockMatrixCase, type BlockMatrixDefinition, type BlockMatrixOptions, type CaseConditions, type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type ExtractPdfPageInkOptions, FALLBACK_FONTS, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, INK_DPI, INK_THRESHOLD, type InventoryEntry, type InventoryMatch, MATRIX_IMAGE, MacOSCoreTextStager, type MappingStatus, type MatrixCanvas, type MatrixEdge, type MatrixFont, NoopFontStager, type PdfFontInfo, type PdfPageInk, type PdfTextLine, type PdfTextPage, type PdfTextWord, type Pgm, PptxFormatAdapter, RENDERED_QUALITY_RULES, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, type RenderedRuleId, type RenderedTextEntry, type RequestedFont, type TextOccurrence, VISIBLE_SPILL_PT, WindowsFontStager, analyzeRenderedDocument, assignInventory, authoredTextForMatch, blockCaseDocument, boundaryInvocation, boundarySlotValue, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, enumerateBlockDefinitions, extractPdfFonts, extractPdfPageInk, extractPdfTextGeometry, familyRendered, generateBlockMatrix, getFontStager, getRasterizerCacheStats, inkedRows, normalizeForMatch, overBudgetInvocation, pageInkFromPgm, parsePdfFonts, parsePdfTextBbox, parsePgm, pdffontsAvailable, pdftotextAvailable, readingOrder, renderedInventoryFromFacts, reportCaseDocument, requestedFontsFromFacts, runWithDiagnosticSink, stderrDiagnosticSink, widestNumber };