@extend-ai/react-pptx 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -8,6 +8,12 @@
 
 ## Unreleased
 
+- Add a cold-start `createPptxThumbnailRenderer` API with package-owned PNG, canvas, ImageBitmap,
+  and SVG outputs, explicit thumbnail font policy, cancellation, bounded concurrency, shared
+  presentation assets, and phase-level performance measurements.
+- Make slide navigation observable before off-window rendering completes, isolate resource
+  readiness per slide mount, update zoom and fit geometry without rebuilding mounted slide DOM,
+  and reduce thumbnail work outside the visible rail.
 - Expose consumer-owned slide thumbnail rails through `usePptxViewerThumbnails`, including stable
   container refs, resolution bounds, render status, imperative rendering, and cleanup. Add
   DOCX-style visible/prefetch render windows and virtualize the built-in thumbnail scrollport.

package/README.md

@@ -150,6 +150,49 @@ return (
 `usePptxViewer` exposes the reactive navigation/search/zoom controller. `onViewportReady`
 provides the internal slide surface for advanced integrations and test harnesses.
 
+## Cold-start thumbnails
+
+`createPptxThumbnailRenderer` renders directly from a `ParsedPresentation`; it does not mount or
+initialize `ReactPptxViewer`. One renderer reuses its font manager, DOM/SVG rendering context, and
+presentation asset cache across slide requests. The parsed presentation can later be passed to
+`ReactPptxViewer` without fetching or parsing it again.
+
+```ts
+import { createPptxThumbnailRenderer, parsePresentation } from '@extend-ai/react-pptx';
+
+const presentation = await parsePresentation(source, {
+  onPerformanceMeasurement: recordMeasurement,
+});
+const renderer = createPptxThumbnailRenderer(presentation, {
+  fonts: {
+    loadEmbeddedFonts: false,
+    waitForFonts: false,
+  },
+  concurrency: 2,
+  onPerformanceMeasurement: recordMeasurement,
+});
+
+const thumbnail = await renderer.renderSlide(0, {
+  maxWidth: 240,
+  maxHeight: 135,
+  output: 'blob',
+  signal: abortController.signal,
+});
+
+image.src = URL.createObjectURL(thumbnail.data);
+renderer.destroy();
+```
+
+The output can be `blob` (PNG, the default), `canvas`, `imageBitmap`, or `svg`. `renderSlides()`
+accepts an explicit index list, preserves its order, and never initializes other slides. Both
+single and batch requests use the renderer's bounded queue. By default, the thumbnail-specific
+font policy skips embedded fonts, global font readiness, and missing-font probing; callers can opt
+back into any of those behaviors through `fonts`.
+
+Performance observers receive `download`, `wasm-parsing`, `embedded-font-preparation`,
+`slide-dom-svg-rendering`, `image-decoding`, and `raster-encoding` measurements as applicable. Each
+render result also contains its slide-specific measurements.
+
 ## Thumbnail hook
 
 `usePptxViewerThumbnails` exposes detached slide previews for a consumer-owned filmstrip. PPTX

package/dist/index.d.ts

@@ -373,6 +373,14 @@ interface ParsedPresentation {
     readonly document: PresentationDocument;
     readonly warnings: readonly PresentationWarning[];
 }
+type PptxPerformancePhase = 'download' | 'wasm-parsing' | 'embedded-font-preparation' | 'slide-dom-svg-rendering' | 'image-decoding' | 'raster-encoding';
+interface PptxPerformanceMeasurement {
+    /** Wall-clock duration for this phase. */
+    durationMs: number;
+    phase: PptxPerformancePhase;
+    /** Present for work attributable to one slide. */
+    slideIndex?: number;
+}
 type PresentationSource = BinaryPresentationSource | PresentationDocument | ParsedPresentation;
 type ViewerMode = 'slide' | 'continuous';
 type FitMode = 'contain' | 'none';
@@ -381,6 +389,8 @@ interface ParsePresentationOptions {
     formatHint?: PresentationFormat;
     maxInputBytes?: number;
     fetchInit?: Omit<RequestInit, 'signal'>;
+    /** Receives cold-start download and native parsing timings. */
+    onPerformanceMeasurement?: (measurement: PptxPerformanceMeasurement) => void;
 }
 interface VirtualizationOptions {
     /**
@@ -466,6 +476,55 @@ interface PptxSlideThumbnailRenderOptions {
     /** Rendered thumbnail width in CSS pixels. */
     width?: number;
 }
+type PptxThumbnailOutput = 'blob' | 'canvas' | 'imageBitmap' | 'svg';
+interface PptxThumbnailRendererOptions {
+    /**
+     * Thumbnail-specific font policy. Defaults to skipping embedded fonts and
+     * not waiting for the global font set.
+     */
+    fonts?: PptxFontOptions;
+    /** Maximum number of slide renders executing at once. Default `2`. */
+    concurrency?: number;
+    onPerformanceMeasurement?: (measurement: PptxPerformanceMeasurement) => void;
+    onWarning?: (warning: PresentationWarning) => void;
+}
+interface PptxThumbnailRenderOptions {
+    maxHeight?: number;
+    maxWidth?: number;
+    /** Output pixel density. Default `1`. */
+    pixelRatio?: number;
+    output?: PptxThumbnailOutput;
+    /** PNG encoding quality where supported. */
+    quality?: number;
+    signal?: AbortSignal;
+}
+interface PptxThumbnailRenderResult<T> {
+    data: T;
+    height: number;
+    measurements: readonly PptxPerformanceMeasurement[];
+    output: PptxThumbnailOutput;
+    slideIndex: number;
+    width: number;
+}
+interface PptxThumbnailRenderer {
+    readonly presentation: ParsedPresentation;
+    readonly ready: Promise<void>;
+    renderSlide(slideIndex: number, options: PptxThumbnailRenderOptions & {
+        output: 'canvas';
+    }): Promise<PptxThumbnailRenderResult<HTMLCanvasElement>>;
+    renderSlide(slideIndex: number, options: PptxThumbnailRenderOptions & {
+        output: 'imageBitmap';
+    }): Promise<PptxThumbnailRenderResult<ImageBitmap>>;
+    renderSlide(slideIndex: number, options: PptxThumbnailRenderOptions & {
+        output: 'svg';
+    }): Promise<PptxThumbnailRenderResult<string>>;
+    renderSlide(slideIndex: number, options?: PptxThumbnailRenderOptions & {
+        output?: 'blob';
+    }): Promise<PptxThumbnailRenderResult<Blob>>;
+    /** Renders exactly the supplied indexes, preserving their order. */
+    renderSlides(slideIndexes: readonly number[], options?: PptxThumbnailRenderOptions): Promise<PptxThumbnailRenderResult<Blob | HTMLCanvasElement | ImageBitmap | string>[]>;
+    destroy(): void;
+}
 interface PptxSlideThumbnailRenderWindow {
     /**
      * Slide indexes whose attached thumbnail containers should render first.
@@ -582,6 +641,8 @@ interface ReactPptxViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'chi
     onSlideUnmounted?: (index: number) => void;
     onSearchResults?: (results: readonly PresentationSearchResult[]) => void;
     onThumbnailRendered?: (index: number, element: HTMLElement) => void;
+    /** Receives parsing, font preparation, and rendering timings. */
+    onPerformanceMeasurement?: (measurement: PptxPerformanceMeasurement) => void;
     /** Supplies the internal slide surface to host integrations and test harnesses. */
     onViewportReady?: (element: HTMLDivElement) => void;
     ref?: Ref<PptxViewerController>;
@@ -628,8 +689,10 @@ declare function usePptxViewer(): UsePptxViewerResult;
  */
 declare function usePptxViewerThumbnails(controller: PptxViewerController | null | undefined, options?: UsePptxViewerThumbnailsOptions): PptxViewerThumbnails;
 
+declare function createPptxThumbnailRenderer(presentation: ParsedPresentation, options?: PptxThumbnailRendererOptions): PptxThumbnailRenderer;
+
 /** Cross-platform, metrically similar substitutions for common Office typefaces. */
 declare const OFFICE_FONT_FALLBACKS: Readonly<Record<string, readonly string[]>>;
 declare function resolvePptxFontFamily(fontFamily: string, options?: Pick<PptxFontOptions, 'fallbacks' | 'fallbackFamilies' | 'useOfficeFallbacks'>): string;
 
-export { type BinaryPresentationSource, type FitMode, OFFICE_FONT_FALLBACKS, type ParsePresentationOptions, type ParsedPresentation, type PptxFontOptions, type PptxFontSource, type PptxSlideThumbnailItem, type PptxSlideThumbnailRenderOptions, type PptxSlideThumbnailRenderWindow, type PptxSlideThumbnailResolution, type PptxSlideThumbnailStatus, type PptxViewerController, PptxViewerError, type PptxViewerThumbnails, type PresentationAsset, type PresentationDocument, type PresentationEmbeddedFont, type PresentationFormat, type PresentationMetadata, type PresentationSearchResult, type PresentationSlide, type PresentationSource, type PresentationTheme, type PresentationWarning, ReactPptxViewer, type ReactPptxViewerProps, type SearchHighlightOptions, type Slide, type SlideComment, type SlideLayout, type SlideMaster, type SlideNode, type SlideNote, type ThumbnailRenderContext, type UsePptxPresentationState, type UsePptxViewerResult, type UsePptxViewerThumbnailsOptions, type ViewerMode, type ViewerSearchOptions, type VirtualizationOptions, type WasmSource, type WorkerWasmSource, initWasm, parsePresentation, presentationParsingDefaults, resolvePptxFontFamily, setWasmSource, usePptxModel, usePptxPresentation, usePptxViewer, usePptxViewerThumbnails };
+export { type BinaryPresentationSource, type FitMode, OFFICE_FONT_FALLBACKS, type ParsePresentationOptions, type ParsedPresentation, type PptxFontOptions, type PptxFontSource, type PptxPerformanceMeasurement, type PptxPerformancePhase, type PptxSlideThumbnailItem, type PptxSlideThumbnailRenderOptions, type PptxSlideThumbnailRenderWindow, type PptxSlideThumbnailResolution, type PptxSlideThumbnailStatus, type PptxThumbnailOutput, type PptxThumbnailRenderOptions, type PptxThumbnailRenderResult, type PptxThumbnailRenderer, type PptxThumbnailRendererOptions, type PptxViewerController, PptxViewerError, type PptxViewerThumbnails, type PresentationAsset, type PresentationDocument, type PresentationEmbeddedFont, type PresentationFormat, type PresentationMetadata, type PresentationSearchResult, type PresentationSlide, type PresentationSource, type PresentationTheme, type PresentationWarning, ReactPptxViewer, type ReactPptxViewerProps, type SearchHighlightOptions, type Slide, type SlideComment, type SlideLayout, type SlideMaster, type SlideNode, type SlideNote, type ThumbnailRenderContext, type UsePptxPresentationState, type UsePptxViewerResult, type UsePptxViewerThumbnailsOptions, type ViewerMode, type ViewerSearchOptions, type VirtualizationOptions, type WasmSource, type WorkerWasmSource, createPptxThumbnailRenderer, initWasm, parsePresentation, presentationParsingDefaults, resolvePptxFontFamily, setWasmSource, usePptxModel, usePptxPresentation, usePptxViewer, usePptxViewerThumbnails };