@openpresentation/opf-pptx 0.13.2 → 0.15.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
+import type { Catalog, Finding, Fonts, LayoutDiagnostic, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
 export declare const packageName = "@openpresentation/opf-pptx";
 
 export declare const releaseLane: Readonly<{
@@ -33,10 +33,9 @@ export interface ImageResolverContext {
   path: string;
 }
 
-export interface FontSchemeDiagnostic { code: "unresolved-font-scheme"; path: string; message: string; id: string; fallback: string }
 export interface MediaProvenanceDiagnostic { code: "media-provenance-omitted"; path: string; message: string }
 /** The chart data cannot be plotted, so a placeholder frame stands in for the chart. */
-export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "data-not-inline" | "dataset-unknown" | "no-rows" | "no-columns" | "single-column-not-numeric" }
+export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "dataset-unknown" | "no-rows" | "no-columns" | "single-column-not-numeric" }
 /** Content with no PowerPoint export (an empty table, an unsupported payload) is replaced by a plain-language placeholder frame. */
 export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; path: string; message: string; reason: "table-has-no-rows" | "unsupported-payload" }
 /**
@@ -51,9 +50,8 @@ export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; pat
 export interface UnresolvedAssetDiagnostic { code: "unresolved-asset"; path: string; message: string; reason?: "unsupported-format" | "svg-malformed" | "svg-no-size" | "svg-too-large" | "svg-unsafe" | "svg-rasterizer-unavailable" | "svg-render-failed" | "svg-unreadable" }
 /** An SVG picture had scripts, `foreignObject`, event handlers, references outside the file, `@import` rules or a DOCTYPE; they were removed from the embedded SVG (on import too). Nothing in an SVG is run or fetched. */
 export interface SvgSanitizedDiagnostic { code: "svg-sanitized"; path: string; message: string }
-/** An SVG slide image with a duotone recolor or a non-rectangular shape exports as its PNG raster, not as a native SVG picture, so the effect applies as in the preview (PowerPoint applies opacity, grayscale and a border to an SVG picture, and those stay native). */
+/** An SVG image block with a duotone recolor or a non-rectangular shape (or an SVG image background with the tile fit) exports as its PNG raster, not as a native SVG picture, so the effect applies as in the preview (PowerPoint applies opacity, grayscale and a border to an SVG picture, and those stay native). */
 export interface SvgImageRasterizedDiagnostic { code: "svg-image-rasterized"; path: string; message: string }
-export interface WatermarkNotExportedDiagnostic { code: "watermark-not-exported"; path: string; message: string }
 /**
  * The chart data was reshaped to export a native chart: a single value column was plotted against row numbers; a one-series construct
  * (pie, doughnut, and with `chartex: "native"` treemap, histogram, pareto, waterfall, funnel, map) kept only its first series; by default
@@ -70,9 +68,9 @@ export interface ChartMappingAdaptedDiagnostic { code: "chart-mapping-adapted";
 /** RR-54 (`full` provenance): a chart or table data record, or the datasets map (`path: "datasets"`), is over the 16 MiB tag limit and is not stored; the native values still export. */
 export interface DataProvenanceOmittedDiagnostic { code: "data-provenance-omitted"; path: string; message: string }
 
-/** A template variable was unfilled and its `example` was used (template export only). */
+/** A template variable was unfilled and its `example` was used (template export only), or a built-in variable such as `{{speaker.name}}` has no source value in the document (`variable-builtin-missing`; it exports as nothing). */
 export interface VariableExampleUsedDiagnostic {
-  code: "variable-example-used";
+  code: "variable-example-used" | "variable-builtin-missing";
   /** JSON pointer of the variable's declaration. */
   path: string;
   message: string;
@@ -112,11 +110,17 @@ export interface ToPptxOptions {
    * unfilled required variable throws `unfilled-variables`, and a value of the wrong kind throws `invalid-variables`.
    */
   variables?: Record<string, unknown>;
-  textMeasurement?: TextMeasurement;
+  /**
+   * The fonts handle: what the renderer's `loadFonts()` returns (`@openpresentation/opf-render/fonts-node`), or any object with a
+   * `textMeasurement` (core's `Fonts`). The exporter lays text out with `fonts.textMeasurement` and always names the chosen
+   * families, never a substitute face. Without it, layout uses core's portable estimate. This is the only way to pass a measurement:
+   * a top-level `textMeasurement` option is not read.
+   */
+  fonts?: Fonts;
   /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
-  /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | WatermarkNotExportedDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
+  /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, and, from core's slide context, `unresolved-reference` (once per reference path) when a layout, theme, colour-scheme or font-scheme reference resolves nowhere (not embedded in the document's `catalogs` and not in a registered catalog): core's engine defaults are drawn instead, and a slide whose layout resolves nowhere, like one with no layout, composes automatically. None of them refuses the export unless `strictReferences` is set. */
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | UnresolvedReferenceDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
@@ -130,6 +134,13 @@ export interface ToPptxOptions {
   svgRasterizer?: (svg: string, size: { width: number; height: number; scale: number; text: boolean }) => Uint8Array | Promise<Uint8Array>;
   seed?: number;
   strictAssets?: boolean;
+  /**
+   * Strict reference policy (OPF 0.15). When true, a layout, theme, colour-scheme or font-scheme reference that resolves
+   * nowhere throws `OPFPptxError` with code `unresolved-reference` (its `path` is the first reference's, its `diagnostics`
+   * core's `unresolved-reference` diagnostics) instead of composing automatically or drawing with the engine default.
+   * Default: the value of `strictAssets`.
+   */
+  strictReferences?: boolean;
   timestamp?: string;
   /**
    * ZIP calendar timestamps, including embedded workbooks, use UTC fields at
@@ -146,25 +157,32 @@ export interface ToPptxOptions {
    * PowerPoint updates on open. Without it a current date is reported as unresolved content.
    */
   date?: string;
-  /** Host-supplied catalog records, as in opf-render. Currently consulted for socialPlatforms (generated socials furniture). */
-  catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** Records for document `catalogs.<kind>.source` URLs (a single source or each entry of an ordered search path), as in opf-render. Currently consulted for socialPlatforms. */
-  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+  /**
+   * The catalogs the host registered (core `Catalog[]`, as for opf-render and core's `resolveSlideContext`): each is matched
+   * against a document group's `catalogs.<group>.source`, and the first is the host default that bare ids use when the document
+   * omits `catalogs.default`. Never fetched. Every reference (slide layouts, themes, colour and font schemes) resolves in the
+   * document's embedded records first, then here; omitted or `[]`, only embedded records resolve. Register the gallery snapshot
+   * explicitly with `catalogs: [defaultCatalog]` from `@openpresentation/opf/catalog`.
+   */
+  catalogs?: readonly Catalog[];
 }
 
 export interface FromPptxOptions {
-  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a slide layout id that resolves to no inline or bundled record reports `unresolved-layout-reference`; a slide whose imported blocks no longer fit the stored content structure reports `content-structure-changed` at `slides.N`, a block id repeated by a duplicated slide `duplicate-block-id`, and a footer section text that disagrees with PowerPoint's section list `section-reference-changed` (docs/document-roundtrip.md). */
+  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a stored slide layout reference that resolves neither in the stored document catalogs, nor in the slide's own stored record, nor in `catalogs` reports `unresolved-reference`; a slide whose imported blocks no longer fit the stored content structure reports `content-structure-changed` at `slides.N`, a block id repeated by a duplicated slide `duplicate-block-id`, and a footer section text that disagrees with PowerPoint's section list `section-reference-changed` (docs/document-roundtrip.md). */
   onDiagnostic?: (diagnostic: {code: string; path: string; message: string}) => void;
   fallbackName?: string;
   schema?: string;
-  /** The export's host catalog records (as in ToPptxOptions). Currently used to recognize unedited socials lines, so authored handles return. */
-  catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** The export's records for document `catalogs.<kind>.source` URLs (as in ToPptxOptions). Currently used for socialPlatforms. */
-  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+  /**
+   * The catalogs the host registered (core `Catalog[]`, as in ToPptxOptions; never fetched). Theme and colour-scheme recovery
+   * (FF-24) matches the package's theme against the first one, the host default: an exact colour-scheme match imports as its
+   * bare id and a corroborated theme name as `design.theme`. Without catalogs the colour scheme imports as an inline object and
+   * no theme id is recovered. A stored slide layout reference also resolves here.
+   */
+  catalogs?: readonly Catalog[];
   /**
    * Opt in to raw per-shape signals (see PptxSignals). `true` uses the default limits; an object lowers or raises them.
-   * With it, `fromPptx` resolves to `{document, signals}`; without it (the default, also `false`/`null`) it resolves
-   * to the OPF document exactly as before. The document is the same either way.
+   * With it, `fromPptx` resolves to `{presentation, signals}`; without it (the default, also `false`/`null`) it resolves
+   * to the presentation alone. The presentation is the same either way.
    */
   signals?: boolean | PptxSignalOptions | null;
 }
@@ -172,7 +190,10 @@ export interface FromPptxOptions {
 export declare class OPFPptxError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
-  readonly issues?: unknown[];
+  /** The `error` findings of the `format` check that refused the input or the imported presentation (`invalid-opf`, `invalid-import-opf`), or the variable errors (`unfilled-variables`, `invalid-variables`). */
+  readonly findings?: Finding[];
+  /** The layout diagnostics behind a `layout-overflow` error, or core's `unresolved-reference` diagnostics behind a strict-export `unresolved-reference` error. */
+  readonly diagnostics?: LayoutDiagnostic[] | UnresolvedReferenceDiagnostic[];
   readonly path?: string;
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
@@ -195,7 +216,7 @@ export declare function fromPptx(input: Uint8Array | ArrayBuffer, options?: From
 
 /** Bounds on the signals. Each is an integer from 1 up to the cap in parentheses; the defaults are DEFAULT_SIGNAL_LIMITS. */
 export interface PptxSignalOptions {
-  /** Slides reported (5000). The document always has every slide. Default 300. */
+  /** Slides reported (5000). The presentation always has every slide. Default 300. */
   maxSlides?: number;
   /** Shapes reported per slide, groups and their members each counting one (5000). Default 300. */
   maxShapesPerSlide?: number;
@@ -221,8 +242,8 @@ export declare const SIGNALS_VERSION: 1;
 export declare function isMonospaceFamily(family: string | undefined): boolean;
 
 export interface PptxImportWithSignals {
-  /** The same OPF document `fromPptx` returns without the option. */
-  document: Record<string, unknown>;
+  /** The same presentation `fromPptx` returns without the option. */
+  presentation: Record<string, unknown>;
   signals: PptxSignals;
 }
 
@@ -252,7 +273,7 @@ export interface PptxSignals {
 }
 
 export interface PptxSlideSignals {
-  /** Slide position, the same index as `document.slides`. */
+  /** Slide position, the same index as `presentation.slides`. */
   index: number;
   /** Package part, for example "ppt/slides/slide1.xml". */
   part: string;
@@ -379,15 +400,16 @@ export interface PptxOutlineSignal extends PptxColor {
   tailArrow?: string;
 }
 
-/** Where a shape went in the OPF document `fromPptx` returned. */
+/** Where a shape went in the presentation `fromPptx` returned. */
 export interface PptxOpfLink {
   /**
    * "block" fed a block (`path`, `blockType`); "title", "subtitle" and "tag" fed that slide field. Other roles name a shape the
-   * importer consumed without a block of its own: "furniture" (footer, date, number, section), "slide-image", "watermark", "logo",
+   * importer consumed without a block of its own: "furniture" (footer, date, number, section), "background" (the picture of an image background),
+   * "image-overlay" (the overlay shape of an image background or image block), "watermark", "logo",
    * and the members of an OPF-tagged group ("code", "metric", "quote", "timeline", "media", "card-frame").
    */
   role: string;
-  /** Path in the document, for example "slides.2.blocks.1", "slides.0.title", or "slides.1.left" after a tagged round trip. */
+  /** Path in the presentation, for example "slides.2.blocks.1", "slides.0.title", or "slides.1.left" after a tagged round trip. */
   path?: string;
   blockType?: string;
 }
@@ -462,9 +484,9 @@ export interface TypefaceInventory {
   fontsUsed: string[] | null;
 }
 
-export interface CheckPptxTypefacesOptions {
-  /** Family names the document chose (heading, body, code, run fonts). Required. */
-  fonts: string[];
+export interface CheckTypefacesOptions {
+  /** Family names the presentation chose (heading, body, code, run fonts). Required. */
+  families: string[];
   /** Chosen families that are monospace; their pitchFamily must be fixed pitch, and only theirs. */
   monospace?: string[];
   /** Allow empty theme ea/cs slots and references to them (FF-05). Default true. */
@@ -482,7 +504,7 @@ export type ThemeScriptSelection = Partial<Record<"major" | "minor", Partial<Rec
 export type TypefaceViolationReason =
   | "foreign-typeface"
   | "foreign-theme-reference"
-  | "unresolved-theme-reference"
+  | "theme-reference-unresolved"
   | "empty-theme-reference"
   | "empty-typeface"
   | "foreign-script-supplement"
@@ -504,11 +526,11 @@ export interface TypefaceViolation {
 
 export declare const THEME_SCRIPT_SUPPLEMENTS: Readonly<Record<"major" | "minor", Readonly<Record<string, string>>>>;
 
-export declare function inventoryPptxTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options?: {nested?: boolean}): TypefaceInventory;
+export declare function inventoryTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options?: {nested?: boolean}): TypefaceInventory;
 
 export declare function packageFontsUsed(inventory: TypefaceInventory): string[];
 
-export declare function checkPptxTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options: CheckPptxTypefacesOptions): {
+export declare function checkTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options: CheckTypefacesOptions): {
   ok: boolean;
   violations: TypefaceViolation[];
   inventory: TypefaceInventory;