@json-to-office/jto-ops 6.2.0 → 7.0.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 {
@@ -59,6 +59,12 @@ interface GeneratorOptions {
     };
     /** Opaque canonical prologue output shared by analysis and rendering. */
     prepared?: PreparedDocument;
+    /**
+     * Registered code components. Quality preparation expands them the way
+     * generation does, so `analyzeQuality` and `prepareDocument` judge what a
+     * plugin emits and report it at the invocation the author wrote (#453).
+     */
+    plugins?: readonly any[];
 }
 interface GeneratorResult {
     generateBuffer: (document: any) => Promise<Buffer>;
@@ -499,6 +505,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 +531,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 +552,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 +573,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 +626,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 +735,144 @@ 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 matrix inventory (#343): every JSON block definition the playground
+ * templates embed, found by the same extraction MCP discovery publishes as
+ * `jto://blocks`, and for each one the conditions it is supported on — theme,
+ * canvas, font, slot edge — with a stated reason for every condition it is
+ * not. Nothing is omitted silently: a condition a definition does not get is
+ * an exclusion with a reason, and a template with no definitions is listed
+ * with none.
+ *
+ * Applicability is decided from the template, never from a list of blocks:
+ *
+ * - A template on a bundled theme is authored against theme roles and
+ *   tokens, so its definitions are supported on every bundled theme of the
+ *   format, in the design faces and in the fallback faces. A report's are
+ *   supported on every page size its themes scale for; a deck's on the slide
+ *   shape the template is drawn on, because that is where its slot budgets
+ *   are measured — another shape lays out, but holds fewer words.
+ * - A template carrying its own theme object is authored against that
+ *   object: absolute geometry fitted to its own faces and its own canvas. Its
+ *   definitions are supported there only; a bundled theme, another canvas or
+ *   a wider fallback face would be a different design, not a boundary.
+ * - A definition with no slots has one document, so `min` is `max`.
+ *
+ * The profile a template's definitions are judged under is the one the
+ * blueprint drawing on that template names; a template no blueprint uses is
+ * judged under the format's default. The module is pure: themes, blueprints
+ * and profiles are handed in, so a new theme or template gains its cases
+ * without an edit here.
+ */
+
+type MatrixFormat = 'docx' | 'pptx';
+interface MatrixTemplateSource {
+    /** File name, as the gallery and `jto://blocks` name it. */
+    name: string;
+    document: unknown;
+}
+interface MatrixBlueprintSource {
+    id: string;
+    format: string;
+    profile: string;
+    /** The template whose definitions the blueprint invokes. */
+    definitions: string;
+}
+interface MatrixProfileSource {
+    id: string;
+    rules?: Readonly<Record<string, {
+        parameters?: Readonly<Record<string, unknown>>;
+    }>>;
+}
+interface MatrixInventoryOptions {
+    /** The bundled theme names of each format. */
+    themes: Readonly<Record<MatrixFormat, readonly string[]>>;
+    blueprints?: readonly MatrixBlueprintSource[];
+    /** Shipped profiles by id, to read the roles a profile requires present. */
+    profiles?: Readonly<Record<string, MatrixProfileSource>>;
+}
+interface MatrixExclusion {
+    /** `theme minimal`, `canvas standard43`, `font fallback`, `edge min`. */
+    condition: string;
+    reason: string;
+}
+interface MatrixConditions {
+    themes: string[];
+    canvases: MatrixCanvas[];
+    fonts: MatrixFont[];
+    edges: MatrixEdge[];
+}
+interface MatrixInventoryTemplate {
+    template: string;
+    format: MatrixFormat;
+    /** The bundled theme the template names, or `inline` for a theme object. */
+    theme: string;
+    /** The blueprint profile its definitions are judged under, when one uses it. */
+    profile?: string;
+    /** Slot roles that profile requires present, so `min` keeps them. */
+    requiredRoles: string[];
+    /** Every definition the template embeds, in authored order. */
+    definitions: string[];
+    /** The conditions a whole-template case is supported on. */
+    conditions: MatrixConditions;
+    exclusions: MatrixExclusion[];
+}
+interface MatrixInventoryEntry extends MatrixConditions {
+    /** `<template>#<definition pointer>`. */
+    id: string;
+    template: string;
+    format: MatrixFormat;
+    name: string;
+    definitionPointer: string;
+    /** Definitions this one invokes, dependencies first. */
+    dependencies: string[];
+    profile?: string;
+    requiredRoles: string[];
+    exclusions: MatrixExclusion[];
+}
+interface MatrixInventory {
+    templates: MatrixInventoryTemplate[];
+    entries: MatrixInventoryEntry[];
+}
+/** Every condition of a format, whether or not a definition gets it. */
+declare function matrixUniverse(format: MatrixFormat, themes: readonly string[]): MatrixConditions;
+declare function templateFormat(name: string, document: unknown): MatrixFormat | undefined;
+/** The inventory over every template handed in, in the order given. */
+declare function buildMatrixInventory(templates: readonly MatrixTemplateSource[], options: MatrixInventoryOptions): MatrixInventory;
+/**
+ * Conditions of the universe an entry neither gets nor excludes, and
+ * conditions it both gets and excludes. Empty for a complete inventory.
+ */
+declare function inventoryGaps(entry: MatrixConditions & {
+    exclusions: readonly MatrixExclusion[];
+}, universe: MatrixConditions): string[];
+/** One line per template and entry, for a suite's log. */
+declare function describeInventory(inventory: MatrixInventory): string;
+
 /**
  * The block boundary matrix (#343, report portion): every JSON block
  * definition a playground template embeds, invoked at the edges of its own
@@ -715,9 +898,11 @@ declare function analyzeRenderedDocument(input: RenderedAnalysisInput, options?:
 type Rec = Record<string, unknown>;
 type MatrixEdge = 'min' | 'max';
 type MatrixFont = 'design' | 'fallback';
-type MatrixCanvas = 'A4' | 'LETTER';
+/** Page sizes for reports; the two slide shapes theme scales key for decks. */
+type MatrixCanvas = 'A4' | 'LETTER' | 'wide169' | 'standard43';
 interface BlockMatrixDefinition {
     name: string;
+    format: MatrixFormat;
     /** The template the definition is embedded in, as the catalog names it. */
     template: string;
     /** Where inside that template: `/props/blocks/<name>`. */
@@ -756,6 +941,26 @@ interface CaseConditions {
     canvas?: MatrixCanvas;
     requiredRoles?: readonly string[];
 }
+/**
+ * The same faces for a deck. PPTX themes take family names and a deck has
+ * no theme overrides, so the fallback case carries an inline copy of the
+ * bundled theme with these two roles replaced.
+ */
+declare const PPTX_FALLBACK_FONTS: {
+    readonly heading: "DejaVu Sans";
+    readonly body: "DejaVu Sans";
+};
+/** 16:9 and 4:3 at the sizes the house deck and PowerPoint use. */
+declare const PPTX_CANVAS_SIZE: {
+    readonly wide169: {
+        readonly slideWidth: 13.333;
+        readonly slideHeight: 7.5;
+    };
+    readonly standard43: {
+        readonly slideWidth: 10;
+        readonly slideHeight: 7.5;
+    };
+};
 /**
  * The face every LibreOffice ships with, bundled inside the application on
  * each platform: what a design font degrades to when the host lacks it, and
@@ -780,7 +985,7 @@ declare const MATRIX_IMAGE = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQA
  */
 declare function widestNumber(length: number, seed?: number): string;
 /** A slot's value at an edge; `undefined` means "leave it out". */
-declare function boundarySlotValue(slot: BlockSlot, name: string, edge: MatrixEdge, seed?: number): unknown;
+declare function boundarySlotValue(slot: BlockSlot, name: string, edge: MatrixEdge, seed?: number, format?: MatrixFormat): unknown;
 /**
  * One invocation of a definition with every slot at the edge: optional slots
  * left out at `min` (so defaults are what renders), every slot at `max`.
@@ -788,18 +993,23 @@ declare function boundarySlotValue(slot: BlockSlot, name: string, edge: MatrixEd
  * is never optional to that profile, so `requiredRoles` keeps it at `min`.
  * Columns whose cells must count the rows do; nothing else knows a block.
  */
-declare function boundaryInvocation(name: string, definition: JsonBlockDefinition, edge: MatrixEdge, seed?: number, requiredRoles?: readonly string[]): Rec;
+declare function boundaryInvocation(name: string, definition: JsonBlockDefinition, edge: MatrixEdge, seed?: number, requiredRoles?: readonly string[], format?: MatrixFormat): Rec;
 /**
  * The same invocation one past the edge: the first budgeted string a word
  * over, or the first bounded array an item over. What a slot violation
  * looks like, so a suite can prove it is reported at the authored pointer.
  */
-declare function overBudgetInvocation(name: string, definition: JsonBlockDefinition, seed?: number): {
+declare function overBudgetInvocation(name: string, definition: JsonBlockDefinition, seed?: number, format?: MatrixFormat): {
     invocation: Rec;
     slot: string;
     kind: 'words' | 'items';
 } | undefined;
-/** Every definition a template embeds, with the template's own example of it. */
+/**
+ * Every definition a template embeds, with the template's own example of it.
+ * The definitions come from the extraction MCP discovery publishes, so the
+ * matrix covers exactly what an agent can copy; a template whose definitions
+ * do not validate is an error here, not a template with fewer blocks.
+ */
 declare function enumerateBlockDefinitions(template: unknown, templateName: string): BlockMatrixDefinition[];
 /**
  * A small report with one block at its edge: the chrome at the template's
@@ -811,6 +1021,49 @@ declare function blockCaseDocument(entries: readonly BlockMatrixDefinition[], na
 declare function reportCaseDocument(template: unknown, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles }?: CaseConditions): Rec;
 /** Every case the options span, in a stable order. */
 declare function generateBlockMatrix(template: unknown, templateName: string, options: BlockMatrixOptions): BlockMatrixCase[];
+interface DeckCaseConditions extends CaseConditions {
+    /**
+     * A bundled theme's object, for the fallback-font case: a deck has no
+     * theme overrides, so the faces go into an inline copy of the theme.
+     */
+    themeObject?: (name: string) => Rec | undefined;
+}
+/**
+ * A deck with one block at its edge: the template's cover at its nominal
+ * values first, when the template has one and it is not the block under
+ * test, so the slide under test is where footer rules start counting.
+ */
+declare function deckBlockCaseDocument(template: unknown, entries: readonly BlockMatrixDefinition[], name: string, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles, themeObject, }?: DeckCaseConditions): Rec;
+/** The whole deck with every invocation at the edge. */
+declare function deckReportCaseDocument(template: unknown, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles, themeObject, }?: DeckCaseConditions): Rec;
+interface MatrixCase extends BlockMatrixCase {
+    format: MatrixFormat;
+    template: string;
+    /** The profile the template's blueprint judges it under, when one does. */
+    profile?: string;
+}
+/** Which of the inventory's supported conditions a run takes. */
+interface MatrixSelection {
+    templates?: readonly string[];
+    themes?: readonly string[];
+    fonts?: readonly MatrixFont[];
+    edges?: readonly MatrixEdge[];
+    canvases?: readonly MatrixCanvas[];
+    /** Whether the per-definition cases are generated. Default true. */
+    blocks?: boolean;
+    /** Whether the whole-template cases are generated. Default true. */
+    report?: boolean;
+}
+/**
+ * Every case the inventory supports under a selection, in a stable order:
+ * template, theme, font, canvas, edge, then each definition before the
+ * whole template. A template whose definitions all lack slots has no
+ * whole-template case: at either edge it is the template itself, which is
+ * gallery coverage.
+ */
+declare function generateMatrixCases(inventory: MatrixInventory, templates: readonly MatrixTemplateSource[], selection?: MatrixSelection, { themeObject }?: {
+    themeObject?: (name: string) => Rec | undefined;
+}): MatrixCase[];
 
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
@@ -1003,4 +1256,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 DeckCaseConditions, 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 MatrixBlueprintSource, type MatrixCanvas, type MatrixCase, type MatrixConditions, type MatrixEdge, type MatrixExclusion, type MatrixFont, type MatrixFormat, type MatrixInventory, type MatrixInventoryEntry, type MatrixInventoryOptions, type MatrixInventoryTemplate, type MatrixProfileSource, type MatrixSelection, type MatrixTemplateSource, NoopFontStager, PPTX_CANVAS_SIZE, PPTX_FALLBACK_FONTS, 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, buildMatrixInventory, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, deckBlockCaseDocument, deckReportCaseDocument, describeInventory, emitDiagnostic, enumerateBlockDefinitions, extractPdfFonts, extractPdfPageInk, extractPdfTextGeometry, familyRendered, generateBlockMatrix, generateMatrixCases, getFontStager, getRasterizerCacheStats, inkedRows, inventoryGaps, matrixUniverse, normalizeForMatch, overBudgetInvocation, pageInkFromPgm, parsePdfFonts, parsePdfTextBbox, parsePgm, pdffontsAvailable, pdftotextAvailable, readingOrder, renderedInventoryFromFacts, reportCaseDocument, requestedFontsFromFacts, runWithDiagnosticSink, stderrDiagnosticSink, templateFormat, widestNumber };