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

package/dist/index.d.ts

@@ -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>;
@@ -753,6 +759,120 @@ declare function requestedFontsFromFacts(format: FormatName, facts: readonly Qua
     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
@@ -778,9 +898,11 @@ declare function requestedFontsFromFacts(format: FormatName, facts: readonly Qua
 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>`. */
@@ -819,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
@@ -843,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`.
@@ -851,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
@@ -874,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
@@ -1066,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, renderedInventoryFromFacts, reportCaseDocument, requestedFontsFromFacts, 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 };