pptx-glimpse 2.0.0 → 3.1.0

package/dist/index.d.ts

@@ -1,541 +1,8 @@
-/**
- * Source handle related types.
- *
- * PptxSourceModel source node is a writer / editor / round-trip
- * In order to do this, we can use ``which package part and which node it came from'' as a stable handle.
- * A handle is not a direct mutable pointer, but a stable reference
- * (see part path / relationship id / node id / order within siblings / raw sidecar)
- * composes it.
- */
-declare const PartPathBrand: unique symbol;
-declare const RelationshipIdBrand: unique symbol;
-declare const SourceNodeIdBrand: unique symbol;
-declare const RawSidecarIdBrand: unique symbol;
-/** Part path inside the OOXML package (Example: `ppt/slides/slide1.xml`). */
-type PartPath = string & {
-    readonly [PartPathBrand]: typeof PartPathBrand;
-};
-/** Relationship id (Example: `rId1`).`_rels/*.rels` source. */
-type RelationshipId = string & {
-    readonly [RelationshipIdBrand]: typeof RelationshipIdBrand;
-};
-/** An id that uniquely points to an element within the source part (spid / generation id, etc.). */
-type SourceNodeId = string & {
-    readonly [SourceNodeIdBrand]: typeof SourceNodeIdBrand;
-};
-/** Id pointing to a raw sidecar. */
-type RawSidecarId = string & {
-    readonly [RawSidecarIdBrand]: typeof RawSidecarIdBrand;
-};
-/**
- * Stable handle describing a source node's provenance. The writer uses the handle to decide whether a generated
- * node can be spliced into an existing part or whether a broader scope must be regenerated.
- *
- */
-interface SourceHandle {
-    /** Package part that owns this node. */
-    readonly partPath: PartPath;
-    /** Node id inside the part (when available). */
-    readonly nodeId?: SourceNodeId;
-    /** The relationship id referencing this node (e.g. `r:embed` in blip). */
-    readonly relationshipId?: RelationshipId;
-    /** The child's order slot within the parent element. Used to restore order with raw sidecar. */
-    readonly orderingSlot?: number;
-    /** Raw sidecar ids associated with this node. */
-    readonly rawSidecarIds?: readonly RawSidecarId[];
-}
+export { C as ConversionDiagnostic, a as ConvertOptions, D as DEFAULT_FONT_MAPPING, F as FontBuffer, b as FontMapping, L as LogLevel, O as OpentypeSetup, P as PngConversionReport, S as SlideImage, c as SlideSupportCoverage, d as SlideSvg, e as SupportCoverage, f as SupportCoverageCounts, g as SvgConversionReport, U as UsedFonts, W as WarningEntry, h as WarningSummary, i as clearFontCache, j as collectUsedFonts, k as convertPptxToPng, l as convertPptxToSvg, n as createFontMapping, o as createOpentypeSetupFromBuffers, p as createOpentypeTextMeasurerFromBuffers, q as getMappedFont, r as getWarningEntries, s as getWarningSummary, t as renderPptxSourceModelToSvg } from './font-collector-BYuaCG-o.js';
+export { PptxSourceModel } from '@pptx-glimpse/document';
 
-/**
- * Font resolver context for text-to-path conversion.
- * Provides access to a Font object with the opentype.js getPath() method.
- */
-interface OpentypePath {
-    toPathData(decimalPlaces?: number): string;
-}
-interface OpentypeFullFont {
-    unitsPerEm: number;
-    ascender: number;
-    descender: number;
-    getPath(text: string, x: number, y: number, fontSize: number): OpentypePath;
-    getAdvanceWidth(text: string, fontSize: number): number;
-}
-interface TextPathFontResolver {
-    resolveFont(fontFamily: string | null | undefined, fontFamilyEa: string | null | undefined, jpanFallback?: string | null): OpentypeFullFont | null;
-}
+type ResvgWasmInput = ArrayBuffer | Uint8Array | Response;
 
-/**
- * Mapping from PPTX font family names to replacement font family names.
- *
- * Keys are font names found in PPTX files. Values are font names that should be
- * present in the rendering environment, commonly open-source alternatives to
- * proprietary Microsoft Office fonts.
- */
-type FontMapping = Record<string, string>;
-/**
- * Default replacement mapping for common Microsoft Office fonts.
- *
- * The table maps fonts such as Calibri, Arial, Meiryo, and MS Gothic to
- * open-source alternatives used during text measurement, SVG path generation,
- * and font lookup.
- */
-declare const DEFAULT_FONT_MAPPING: Readonly<FontMapping>;
-/**
- * Create a font mapping table by merging defaults with user overrides.
- *
- * @param userMapping Custom PPTX font name to replacement font name entries.
- * User-specified entries take precedence over `DEFAULT_FONT_MAPPING`.
- * @returns A new mutable mapping object.
- */
-declare function createFontMapping(userMapping?: FontMapping): FontMapping;
-/**
- * Look up the replacement font for a PPTX font family.
- *
- * Matching is case-insensitive and normalizes full-width alphanumeric
- * characters used by some Japanese Office font names.
- *
- * @param fontFamily PPTX font family name to resolve.
- * @param mapping Mapping table, usually from `createFontMapping`.
- * @returns The replacement font name, or `null` when no mapping exists.
- */
-declare function getMappedFont(fontFamily: string | null | undefined, mapping: FontMapping): string | null;
+declare function initResvgWasm(wasm?: ResvgWasmInput): Promise<void>;
 
-/**
- * Interface for measuring text width and line height.
- * By default, measurement uses static font metrics.
- * Users can pass their own implementation to ConvertOptions.textMeasurer
- * Can be replaced with any measurement backend such as Canvas API or opentype.js.
- */
-interface TextMeasurer {
-    /**
-     * Returns the estimated width of the text in pixels.
-     * @param text - text to measure
-     * @param fontSizePt - font size (points)
-     * @param bold - whether the text is bold
-     * @param fontFamily - font family name for Latin text
-     * @param fontFamilyEa - font family name for East Asian text
-     */
-    measureTextWidth(text: string, fontSizePt: number, bold: boolean, fontFamily?: string | null, fontFamilyEa?: string | null): number;
-    /**
-     * Returns the font's natural line height ratio (line height / font size).
-     * Returns 1.2 as a fallback value if the metric is unknown.
-     * @param fontFamily - font family name for Latin text
-     * @param fontFamilyEa - font family name for East Asian text
-     */
-    getLineHeightRatio(fontFamily?: string | null, fontFamilyEa?: string | null): number;
-    /**
-     * Font ascender ratio (ascender / unitsPerEm) .
-     * Used for baseline offset calculation in the first row.
-     * Returns 1.0 as a fallback value if the metric is unknown.
-     * @param fontFamily - font family name for Latin text
-     * @param fontFamilyEa - font family name for East Asian text
-     */
-    getAscenderRatio(fontFamily?: string | null, fontFamilyEa?: string | null): number;
-}
-
-interface OpentypeGlyph {
-    advanceWidth?: number;
-}
-interface OpentypeFont {
-    unitsPerEm: number;
-    ascender: number;
-    descender: number;
-    stringToGlyphs(text: string): OpentypeGlyph[];
-}
-declare class OpentypeTextMeasurer implements TextMeasurer {
-    private fonts;
-    private defaultFont;
-    private warnedFonts;
-    /**
-     * @param fonts - font name -> opentype.js Map of Font objects
-     * @param defaultFont - fallback font (optional)
-     */
-    constructor(fonts: Map<string, OpentypeFont>, defaultFont?: OpentypeFont);
-    measureTextWidth(text: string, fontSizePt: number, bold: boolean, fontFamily?: string | null, fontFamilyEa?: string | null): number;
-    getLineHeightRatio(fontFamily?: string | null, fontFamilyEa?: string | null): number;
-    getAscenderRatio(fontFamily?: string | null, fontFamilyEa?: string | null): number;
-    private resolveBoldFont;
-    private resolveFont;
-}
-
-/**
- * Font file data supplied directly by the caller.
- *
- * Use this when system font scanning is unavailable or undesirable, such as in
- * serverless environments. `name` is used to register TTF/OTF buffers under a
- * specific family name; TTC buffers also read family names from their names
- * table.
- */
-interface FontBuffer {
-    /**
-     * Optional font family name to register for this buffer.
-     */
-    name?: string;
-    /**
-     * Raw TTF, OTF, or TTC font file bytes.
-     */
-    data: ArrayBuffer | Uint8Array;
-}
-/**
- * Create a text measurer from caller-provided font buffers.
- *
- * This low-level helper is useful when rendering in an environment where fonts
- * are bundled as bytes instead of discovered from the OS. It dynamically imports
- * `opentype.js` and returns `null` if no fonts can be parsed or the optional
- * dependency is unavailable.
- *
- * @param fontBuffers Font file bytes to parse.
- * @param fontMapping Optional PPTX font name to replacement font mapping.
- * @returns A text measurer, or `null` when setup is not possible.
- */
-declare function createOpentypeTextMeasurerFromBuffers(fontBuffers: FontBuffer[], fontMapping?: FontMapping): Promise<OpentypeTextMeasurer | null>;
-/**
- * Font services created from OpenType font data.
- */
-interface OpentypeSetup {
-    /**
-     * Measures text width for layout and wrapping.
-     */
-    measurer: OpentypeTextMeasurer;
-    /**
-     * Resolves fonts for converting text to SVG path outlines.
-     */
-    fontResolver: TextPathFontResolver;
-}
-/**
- * Create font measurement and SVG path resolution services from font buffers.
- *
- * Use this for advanced integrations that need to provide fonts explicitly
- * instead of relying on system font directories. Returned services can be wired
- * into renderer internals; the public conversion APIs usually only need
- * `fontDirs`, `skipSystemFonts`, and `fontMapping`.
- *
- * @param fontBuffers TTF, OTF, or TTC font file bytes.
- * @param fontMapping Optional PPTX font name to replacement font mapping.
- * @returns Font services, or `null` when no usable font setup can be created.
- */
-declare function createOpentypeSetupFromBuffers(fontBuffers: FontBuffer[], fontMapping?: FontMapping): Promise<OpentypeSetup | null>;
-/**
- * Clear the module-level cache of parsed system fonts.
- *
- * Conversion APIs cache parsed font objects for repeated calls with the same
- * font options. Call this after installing, removing, or replacing fonts in a
- * long-running process when subsequent conversions must reload font files.
- */
-declare function clearFontCache(): void;
-
-/**
- * Initialize the resvg-wasm module used for PNG conversion.
- *
- * Calling this is optional because `convertPptxToPng` initializes resvg-wasm on
- * first use. Applications may call it during startup to pay the WASM loading
- * cost before handling the first conversion request.
- */
-declare function initResvgWasm(): Promise<void>;
-
-/**
- * Controls how unsupported-feature warnings are collected and printed.
- *
- * `"off"` disables collection, `"warn"` collects entries and prints summaries,
- * and `"debug"` also prints each warning as it is recorded.
- */
-type LogLevel = "off" | "warn" | "debug";
-/**
- * One unsupported or approximated feature encountered during conversion.
- */
-interface WarningEntry {
-    /**
-     * Stable feature key, for example `"sp.style"` or `"bodyPr@vert"`.
-     */
-    feature: string;
-    /**
-     * Human-readable warning message.
-     */
-    message: string;
-    /**
-     * Optional location context, for example `"Slide 1"`.
-     */
-    context?: string;
-}
-/**
- * Aggregated warnings from the most recent conversion cycle.
- */
-interface WarningSummary {
-    /**
-     * Total number of warning entries.
-     */
-    totalCount: number;
-    /**
-     * Warning counts grouped by feature key.
-     */
-    features: {
-        feature: string;
-        message: string;
-        count: number;
-    }[];
-}
-/**
- * Return a grouped summary of currently collected warnings.
- *
- * This reads the active warning logger state. The public conversion APIs flush
- * warnings at the end of a conversion so summaries can be printed; after that
- * flush, this returns an empty summary until new warnings are recorded. It is
- * mainly useful for lower-level renderer workflows, tests, and integrations
- * that manage the warning cycle directly.
- */
-declare function getWarningSummary(): WarningSummary;
-/**
- * Return individual warning entries collected in the current warning cycle.
- *
- * Entries include optional slide or element context when available. The public
- * conversion APIs flush entries at the end of a conversion, so this is mainly
- * useful for lower-level renderer workflows, tests, and integrations that
- * manage the warning cycle directly.
- */
-declare function getWarningEntries(): readonly WarningEntry[];
-
-/**
- * Options shared by PPTX-to-SVG and PPTX-to-PNG conversion.
- */
-interface ConvertOptions {
-    /**
-     * Target slide numbers to convert, using PowerPoint-style 1-based numbering.
-     *
-     * When omitted, every slide in the presentation is converted. Missing or
-     * out-of-range slide numbers produce no output for those entries.
-     */
-    slides?: number[];
-    /**
-     * Output width in pixels.
-     *
-     * PNG output rasterizes to this width while preserving the slide aspect
-     * ratio. Defaults to 960. SVG output keeps the slide's native pixel size from
-     * the PPTX slide dimensions and does not use this option.
-     */
-    width?: number;
-    /**
-     * Output height in pixels.
-     *
-     * PNG rasterization currently always uses `width`, either the provided value
-     * or the default width, so this option is ignored by the public conversion
-     * APIs. SVG output keeps the slide's native pixel size and does not use this
-     * option.
-     */
-    height?: number;
-    /**
-     * Warning log level for unsupported or approximated PPTX features.
-     *
-     * Defaults to `"off"`. Diagnostics are always collected in the conversion
-     * report; this option only controls console output. Use `"warn"` to print
-     * summaries, or `"debug"` to print individual warning entries as they are
-     * recorded.
-     */
-    logLevel?: LogLevel;
-    /**
-     * Additional directories that are scanned for font files.
-     *
-     * These directories are searched in addition to system font directories unless
-     * `skipSystemFonts` is true.
-     */
-    fontDirs?: string[];
-    /**
-     * Custom PPTX font name to replacement font name mapping.
-     *
-     * Entries are merged with `DEFAULT_FONT_MAPPING`; user-provided entries take
-     * precedence. This is useful when a PPTX references proprietary or corporate
-     * fonts that should render with installed alternatives.
-     */
-    fontMapping?: FontMapping;
-    /**
-     * Skip OS system font directories and only scan `fontDirs`.
-     *
-     * This is useful in containers or serverless environments where bundled fonts
-     * should be the only fonts used.
-     */
-    skipSystemFonts?: boolean;
-    /**
-     * Text output mode for SVG conversion.
-     *
-     * Defaults to `"path"`, which emits glyph outlines as `<path>` elements and
-     * does not require fonts in the SVG viewing environment. `"text"` emits native
-     * `<text>` elements with subset-font `@font-face` data URIs, enabling browser
-     * text selection and native text rendering for inline SVG.
-     *
-     * Embedded fonts and native text may not render as expected when the SVG is
-     * loaded through `<img src="...svg">` or sanitized. `convertPptxToPng` ignores
-     * this option and always renders with `"path"` output because resvg does not
-     * interpret the embedded `@font-face` rules used by SVG text output.
-     */
-    textOutput?: "path" | "text";
-}
-/**
- * SVG conversion result for one slide.
- */
-interface SlideSvg {
-    /**
-     * Original slide number in the PPTX file, using 1-based numbering.
-     */
-    slideNumber: number;
-    /**
-     * Complete SVG document string for the slide.
-     */
-    svg: string;
-}
-/**
- * PNG conversion result for one slide.
- */
-interface SlideImage {
-    /**
-     * Original slide number in the PPTX file, using 1-based numbering.
-     */
-    slideNumber: number;
-    /**
-     * PNG image bytes for the rendered slide.
-     */
-    png: Buffer;
-    /**
-     * Actual output image width in pixels after rasterization.
-     */
-    width: number;
-    /**
-     * Actual output image height in pixels after rasterization.
-     */
-    height: number;
-}
-interface ConversionDiagnostic {
-    readonly source: "document" | "computed-view" | "renderer-adapter" | "renderer";
-    readonly severity: "info" | "warning" | "error";
-    readonly code: string;
-    readonly message: string;
-    readonly slideNumber?: number;
-    readonly sourcePartPath?: string;
-    readonly context?: string;
-    readonly handle?: SourceHandle;
-}
-interface SupportCoverageCounts {
-    /**
-     * Number of PPTX source/computed elements considered for rendering.
-     */
-    readonly inputElements: number;
-    /**
-     * Number of renderer-model elements produced for SVG / PNG output.
-     */
-    readonly outputElements: number;
-    /**
-     * Elements or raw nodes skipped because they are outside the supported render subset.
-     */
-    readonly skippedElements: number;
-    /**
-     * Elements skipped because a referenced PPTX part or relationship could not be resolved.
-     */
-    readonly unresolvedElements: number;
-    /**
-     * Elements or properties rendered with a fallback or ignored unsupported property.
-     */
-    readonly fallbackElements: number;
-    /**
-     * Diagnostics with warning severity that affect support/renderability confidence.
-     */
-    readonly warnings: number;
-}
-interface SlideSupportCoverage extends SupportCoverageCounts {
-    readonly slideNumber: number;
-}
-interface SupportCoverage {
-    /**
-     * Support/renderability coverage summary. This is not a visual-match or pixel accuracy metric.
-     */
-    readonly overall: SupportCoverageCounts;
-    readonly slides: readonly SlideSupportCoverage[];
-}
-interface SvgConversionReport {
-    readonly slides: readonly SlideSvg[];
-    readonly diagnostics: readonly ConversionDiagnostic[];
-    readonly supportCoverage: SupportCoverage;
-}
-interface PngConversionReport {
-    readonly slides: readonly SlideImage[];
-    readonly diagnostics: readonly ConversionDiagnostic[];
-    readonly supportCoverage: SupportCoverage;
-}
-/**
- * Convert a PPTX file to SVG documents.
- *
- * @param input PPTX binary data as a Node.js `Buffer` or `Uint8Array`.
- * @param options Conversion options. `slides` uses 1-based slide numbers; when
- * omitted, all slides are converted.
- * @returns A conversion report containing converted slides, diagnostics, and support coverage.
- *
- * Text is emitted as SVG paths by default for portable rendering. Set
- * `textOutput: "text"` to emit native `<text>` elements with embedded subset
- * fonts for inline browser SVG use. Font directories and font mapping options
- * control how PPTX font names are resolved for text measurement and text output.
- */
-declare function convertPptxToSvg(input: Buffer | Uint8Array, options?: ConvertOptions): Promise<SvgConversionReport>;
-/**
- * Convert a PPTX file to PNG images.
- *
- * @param input PPTX binary data as a Node.js `Buffer` or `Uint8Array`.
- * @param options Conversion options. `slides` uses 1-based slide numbers; when
- * omitted, all slides are converted.
- * @returns A conversion report containing converted PNG slides, diagnostics, and support coverage.
- *
- * PNG conversion first renders each slide to SVG and then rasterizes it with
- * resvg. The `textOutput` option is intentionally ignored: PNG rendering always
- * uses path-based text output because resvg does not interpret the embedded
- * `@font-face` rules used by SVG text mode. Font directories and font mapping
- * options are still used to resolve glyph outlines and text metrics.
- */
-declare function convertPptxToPng(input: Buffer | Uint8Array, options?: ConvertOptions): Promise<PngConversionReport>;
-
-/**
- * Font names discovered in a PPTX file.
- */
-interface UsedFonts {
-    /**
-     * Theme font slots resolved from the presentation's default theme.
-     */
-    theme: {
-        /**
-         * Major Latin theme font.
-         */
-        majorFont: string;
-        /**
-         * Minor Latin theme font.
-         */
-        minorFont: string;
-        /**
-         * Major East Asian theme font, when present.
-         */
-        majorFontEa: string | null;
-        /**
-         * Minor East Asian theme font, when present.
-         */
-        minorFontEa: string | null;
-        /**
-         * Major complex-script theme font, when present.
-         */
-        majorFontCs: string | null;
-        /**
-         * Minor complex-script theme font, when present.
-         */
-        minorFontCs: string | null;
-    };
-    /**
-     * Unique sorted font names used by text runs, bullets, and theme font slots.
-     */
-    fonts: string[];
-}
-/**
- * Parse a PPTX file and collect the font names it references.
- *
- * This is a lightweight preflight helper: it reads the document model and text
- * styles but does not render slides or load font files. Use it to decide which
- * fonts should be installed, bundled, or mapped before calling the conversion
- * APIs.
- *
- * @param input PPTX binary data as a Node.js `Buffer` or `Uint8Array`.
- * @returns Theme font slots and a unique sorted list of referenced font names.
- */
-declare function collectUsedFonts(input: Buffer | Uint8Array): UsedFonts;
-
-export { type ConversionDiagnostic, type ConvertOptions, DEFAULT_FONT_MAPPING, type FontBuffer, type FontMapping, type LogLevel, type OpentypeSetup, type PngConversionReport, type SlideImage, type SlideSupportCoverage, type SlideSvg, type SupportCoverage, type SupportCoverageCounts, type SvgConversionReport, type UsedFonts, type WarningEntry, type WarningSummary, clearFontCache, collectUsedFonts, convertPptxToPng, convertPptxToSvg, createFontMapping, createOpentypeSetupFromBuffers, createOpentypeTextMeasurerFromBuffers, getMappedFont, getWarningEntries, getWarningSummary, initResvgWasm };
+export { type ResvgWasmInput, initResvgWasm };