teamsync-pdf-viewer 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.8.1] — 2026-09-19
+
+### Added
+- **Document Comparison UX Enhancements**:
+  - **Interactive Draggable Separator**: Introduced a movable vertical split separator between documents with real-time percentage split adjustment and smooth cursor dragging.
+  - **Optimal 90% Container Auto-Fit**: Implemented proportional viewport scaling that fits comparison documents to 90% of their split container window width, ensuring readable document layout with comfortable breathing room around margins.
+  - **Split Viewport Zoom & Pan Controls**: Added visible zoom in/out, fit to width, fit to page, and pan tool controls directly inside the comparison toolbar header for each split pane.
+  - **Comparison Demo Shortcut**: Added a one-click "Compare PDF" sample button to the demo top bar and URL query parameter support (`?compare=true`) for direct deep linking.
+- **Dynamic Office Conversion Credentials**:
+  - Client and server support for per-request converter credentials via `x-gotenberg-endpoint` and `x-gotenberg-token` headers, enabling multi-tenant and customer-provided conversion backends.
+
+### Security
+- **SSRF Prevention & Loopback Defense**: Strict validation of remote conversion URLs in `/api/convert`, blocking loopback (`127.0.0.0/8`, `::1`), link-local (`169.254.0.0/16`, `fe80::/10`), private RFC1918 subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), unique local IPv6 (`fc00::/7`), and major cloud provider metadata endpoints (AWS, Azure, GCP, Oracle Cloud).
+- **SSRF Redirect Traversal Defense**: Enforced `{ redirect: 'manual' }` on upstream remote file retrieval in edge functions, terminating HTTP 3xx redirect attempts with HTTP 400 Bad Request to prevent redirect-based SSRF circumvention.
+- **Microservice Boundary Limits**: Enforced strict 100MB download caps, 60s request timeout abort controllers, and validated content types to mitigate denial-of-service and memory exhaustion attacks.
+- **Server Error Sanitization**: Sanitized edge conversion error responses returned to clients, ensuring low-level LibreOffice/Gotenberg stack traces and server-side errors are captured only in internal server logs.
+- **Cross-Window PostMessage Restriction**: Replaced wildcard `*` target origin in iframe communication bridges with caller origin verification or explicit `trustedOrigins` configuration.
+- **Safe Regular Expression & ReDoS Mitigation**: Bounded regex evaluation length and introduced defensive execution caps in document search and redaction utilities to prevent catastrophic regex backtracking.
+- **PDF Link URI Protocol Sanitization**: Added strict protocol validation to embedded PDF links and annotation actions, rejecting malicious URI schemes (`javascript:`, `vbscript:`, `data:`) before execution.
+- **Production Deployment Security Headers**: Added `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, and `Permissions-Policy` to production edge deployments in `vercel.json`.
+- **Security Policy**: Added repository `SECURITY.md` establishing supported versions and responsible vulnerability disclosure workflows.
+
+### Fixed
+- **TypeScript Declaration Emission**: Configured `outDir: 'dist/src'` in `vite.config.ts` to ensure clean TypeScript `.d.ts` declaration generation conforming with `publint` and package exports.
+
+## [1.8.0] — 2026-09-17
+
+### Added
+- **Native Microsoft Office Document Viewing**:
+  - View Microsoft Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), and PowerPoint (`.pptx`, `.ppt`) documents natively inside `<TeamSyncViewer>`.
+  - Transparent document type detection via magic byte signatures and file extension inspection (`officeDetector.ts`).
+  - Animated conversion loading overlay (`OfficeLoadingOverlay.tsx`) with real-time status indication.
+  - Local drag-and-drop and toolbar file picker conversion fallback.
+- **Enterprise Hybrid Office Architecture**:
+  - **Edge CDN Pre-Conversion & Caching**: Fast 200–400ms cached vector PDF delivery via `/api/convert?file=...` with zero server CPU load on repeat views.
+  - **Client-Side On-The-Fly Fallback**: Multipart form upload proxy for local user file drops and selection via `POST /api/convert`.
+  - **Zero Leaked Secrets**: Gotenberg credentials injected server-side; client bundles never expose backend credentials.
+- **Host SDK Office Module**:
+  - Exported `useOfficeDocument` React hook for host applications to manage loading, pre-conversion, and error states before mounting the viewer.
+  - Exported `preloadOfficeDocument(fileOrUrl, config, fileName)` async helper for routers, loaders, and prefetching.
+  - Exported `officeConverter` client service supporting remote URL conversion (`convertOfficeUrl`) and multipart file uploads (`convertOfficeFile`).
+  - Added dedicated `./office` subpath export in `package.json` alongside root exports.
+  - Exported office detection utilities: `isOfficeDocumentUrl`, `isOfficeFile`, `detectOfficeType`, `isOfficeExtension`, `SUPPORTED_OFFICE_EXTENSIONS`.
+  - Exported TypeScript types: `OfficeConversionConfig`, `OfficeConversionState`, `OfficeFileType`, `OfficeDocumentOptions`, `UseOfficeDocumentResult`.
+- **Top-Level SDK Version Export & About Modal Synchronization**:
+  - Exported `VERSION` constant from `teamsync-pdf-viewer` public API.
+  - Automated build-time version synchronization script (`scripts/sync-version.mjs`) ensuring parity across package and git tags.
+  - Dynamic About modal reflecting the active release tag with a direct link to GitHub release notes.
+  - Edge release endpoint (`/api/version`) caching GitHub release metadata at the CDN edge.
+
 ## [1.7.1] — 2026-09-15
 
 ### Fixed

package/README.md

@@ -71,6 +71,7 @@ Explore detailed SDK guides, parameter options, code snippets, and architecture
 - 🎨 **[Annotations & Markup Guide](docs/wiki/Annotations-&-Markup-Guide.md)**: Freehand drawing, vector shapes, callouts & links.
 - 🛡️ **[Redactions & PII Sanitization Guide](docs/wiki/Redactions-&-PII-Sanitization.md)**: Binary redactions, regex PII scanning & discard options.
 - 💧 **[Forensic Watermarking Guide](docs/wiki/Forensic-Watermarking.md)**: Dynamic single and tiled watermark setup.
+- 📄 **[Viewing Office Documents Guide](docs/wiki/Viewing-Office-Documents.md)**: Word (.docx), PowerPoint (.pptx), Excel (.xlsx) high-fidelity viewing & conversion.
 - 🔌 **[Plugin Architecture Guide](docs/wiki/Plugin-Architecture.md)**: Writing custom extension plugins.
 
 ---

package/dist/src/components/CompareToolbar.d.ts

@@ -8,6 +8,13 @@ interface CompareToolbarProps {
     onPrevDiff: () => void;
     onNextDiff: () => void;
     onExit: () => void;
+    is90Fit?: boolean;
+    zoomMultiplier?: number;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
+    onFit90?: () => void;
+    activeTool?: string | null;
+    onSetTool?: (tool: string | null) => void;
 }
-export default function CompareToolbar({ compareState, onSetMode, onSetColors, onToggleCurtain, onPrevDiff, onNextDiff, onExit }: CompareToolbarProps): React.JSX.Element;
+export default function CompareToolbar({ compareState, onSetMode, onSetColors, onToggleCurtain, onPrevDiff, onNextDiff, onExit, is90Fit, zoomMultiplier, onZoomIn, onZoomOut, onFit90, activeTool, onSetTool }: CompareToolbarProps): React.JSX.Element;
 export {};

package/dist/src/components/SideBySideViewer.d.ts

@@ -25,6 +25,10 @@ interface SideBySideViewerProps {
     onSelectDiff?: (id: string) => void;
     onScrollSync?: (scrollTop: number, scrollLeft: number) => void;
     hideAnnotationsUntilPageRendered?: boolean;
+    is90Fit?: boolean;
+    zoomMultiplier?: number;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
 }
-export default function SideBySideViewer({ pdfDocA, pdfDocB, pageNum, scale, rotation, basePageDims, activeTab, activeTool, annotations, watermark, watermarkText, redactions, diffsA, diffsB, selectedDiffId, onSelectDiff, hideAnnotationsUntilPageRendered }: SideBySideViewerProps): React.JSX.Element;
+export default function SideBySideViewer({ pdfDocA, pdfDocB, pageNum, scale, rotation, basePageDims, activeTab, activeTool, annotations, watermark, watermarkText, redactions, diffsA, diffsB, selectedDiffId, onSelectDiff, hideAnnotationsUntilPageRendered, is90Fit, zoomMultiplier, onZoomIn, onZoomOut, }: SideBySideViewerProps): React.JSX.Element;
 export {};

package/dist/src/components/TeamSyncViewer.d.ts

@@ -3,6 +3,7 @@ import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
 import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
 import { Annotation } from '../annotations/types';
+import { OfficeConverterConfig, OfficeFileType } from '../office';
 export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     /** URL of the PDF to display. Alias of `initialDoc`; `fileUrl` wins when both are set. */
     fileUrl?: string;
@@ -74,6 +75,28 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
      * Call `event.preventDefault()` to suppress default behavior.
      */
     onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
+    /**
+     * Configuration for viewing Microsoft Office documents (.docx, .doc, .pptx, .ppt, .xlsx, .xls).
+     */
+    officeConverter?: OfficeConverterConfig;
+    /** Fires when an Office document starts converting to PDF. */
+    onOfficeConverting?: (info: {
+        fileType: OfficeFileType;
+        url?: string;
+        fileName?: string;
+    }) => void;
+    /** Fires when an Office document has successfully converted to PDF. */
+    onOfficeConverted?: (info: {
+        fileType: OfficeFileType;
+        url?: string;
+        fromCache: boolean;
+    }) => void;
+    /** Fires when an Office document conversion encounters an error. */
+    onOfficeConversionError?: (info: {
+        fileType: OfficeFileType;
+        error: Error;
+        url?: string;
+    }) => void;
     className?: string;
     style?: React.CSSProperties;
 }

package/dist/src/core/types.d.ts

@@ -4,7 +4,8 @@ import { Annotation } from '../annotations/types';
 import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
 import { WebViewerInstance } from './ViewerInstance';
-export type { PdfAssetPaths, WebViewerInstance };
+import { OfficeConverterConfig, OfficeFileType } from '../office/types';
+export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType };
 export interface SearchBounds {
     x: number;
     y: number;
@@ -134,7 +135,14 @@ export interface WebViewerOptions {
     onRedactionsChange?: (redactions: Redaction[]) => void;
     /** Fires once per user click of Apply in the confirmation modal with all applied redactions. */
     onRedactionsApplied?: (redactions: Redaction[]) => void;
-    /** Unique identifier for this viewer instance, allowing other viewers to target it by name. */
+    /**
+     * Configuration for viewing Microsoft Office documents (.docx, .doc, .pptx, .ppt, .xlsx, .xls).
+     * Supports headless backend conversion (Gotenberg / LibreOffice daemon) or custom conversion hooks.
+     */
+    officeConverter?: OfficeConverterConfig;
+    /**
+     * Unique identifier for this viewer instance, allowing other viewers to target it by name.
+     */
     id?: string;
     /**
      * Target viewer instance, ref, getter, or instance ID to open cross-document links in.
@@ -228,6 +236,24 @@ export interface ViewerEventMap {
         text: string;
     };
     linkClicked: LinkClickEvent;
+    /** Fires when an Office document begins conversion. */
+    officeConverting: {
+        fileType: OfficeFileType;
+        url?: string;
+        fileName?: string;
+    };
+    /** Fires when an Office document finishes conversion successfully. */
+    officeConverted: {
+        fileType: OfficeFileType;
+        url?: string;
+        fromCache: boolean;
+    };
+    /** Fires when an Office document conversion fails. */
+    officeConversionError: {
+        fileType: OfficeFileType;
+        error: Error;
+        url?: string;
+    };
     destroy: Record<string, never>;
 }
 export type ViewerEventType = keyof ViewerEventMap;

package/dist/src/index.d.ts

@@ -40,3 +40,11 @@ export type { ScrollCompensationParams, ScrollPosition } from './utils/zoomUtils
 export { estimatePageDimensions, computeRowLayout, DEFAULT_FALLBACK_DIMS, hasDimensionMismatch } from './utils/layoutUtils';
 export type { PageDimension, RowLayout } from './utils/layoutUtils';
 export * from './plugins/types';
+export * from './office';
+export { officeConverter, convertOfficeDocument, convertOfficeFile, convertOfficeUrl, } from './office/officeConverter';
+export { useOfficeDocument, preloadOfficeDocument, } from './office/useOfficeDocument';
+export type { UseOfficeDocumentOptions, UseOfficeDocumentResult, } from './office/useOfficeDocument';
+export { isOfficeDocumentUrl, isOfficeFile, detectOfficeType, isOfficeExtension, SUPPORTED_OFFICE_EXTENSIONS, } from './office/officeDetector';
+export { OfficeLoadingOverlay } from './office/OfficeLoadingOverlay';
+export type { OfficeConverterConfig, OfficeConversionConfig, OfficeConversionState, OfficeFileType, OfficeDocumentOptions, OfficeDocumentInfo, } from './office/types';
+export { VERSION } from './version';

package/dist/src/office/OfficeLoadingOverlay.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { OfficeFileType } from './types';
+export interface OfficeLoadingOverlayProps {
+    fileType: OfficeFileType;
+    fileName?: string;
+    error?: Error | null;
+    onRetry?: () => void;
+}
+export declare const OfficeLoadingOverlay: React.FC<OfficeLoadingOverlayProps>;

package/dist/src/office/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './officeDetector';
+export * from './officeConverter';
+export * from './OfficeLoadingOverlay';
+export * from './useOfficeDocument';

package/dist/src/office/officeConverter.d.ts

@@ -0,0 +1,46 @@
+import { OfficeConverterConfig, OfficeFileType } from './types';
+/**
+ * Retrieves a cached converted PDF from memory or sessionStorage.
+ */
+export declare function getCachedOfficePdf(fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, cacheMode?: OfficeConverterConfig['cache']): Promise<ArrayBuffer | null>;
+/**
+ * Stores a converted PDF in memory and optionally sessionStorage.
+ */
+export declare function setCachedOfficePdf(fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, pdfBuffer: ArrayBuffer, cacheMode?: OfficeConverterConfig['cache']): Promise<void>;
+/**
+ * Clears the converted document cache.
+ */
+export declare function clearOfficeCache(): void;
+export interface ConvertOfficeDocumentResult {
+    /** Raw PDF ArrayBuffer ready for PDF.js or downstream processing */
+    pdfBuffer: ArrayBuffer;
+    /** Browser Blob Object URL (e.g. blob:http...) ready for rendering or iframe preview */
+    objectUrl: string;
+    /** Whether the document was served from cache */
+    fromCache: boolean;
+}
+/**
+ * Converts an Office document (Word, PowerPoint, Excel) into a standardized PDF ArrayBuffer
+ * and Blob URL using either a custom converter or the configured backend microservice.
+ */
+export declare function convertOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Convenience helper to convert a remote Office document URL.
+ */
+export declare function convertOfficeUrl(url: string, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Convenience helper to convert a local Office File or Blob.
+ */
+export declare function convertOfficeFile(file: File | Blob, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Unified Office converter service object.
+ */
+export declare const officeConverter: {
+    convert: typeof convertOfficeDocument;
+    convertDocument: typeof convertOfficeDocument;
+    convertUrl: typeof convertOfficeUrl;
+    convertFile: typeof convertOfficeFile;
+    getCached: typeof getCachedOfficePdf;
+    setCached: typeof setCachedOfficePdf;
+    clearCache: typeof clearOfficeCache;
+};

package/dist/src/office/officeDetector.d.ts

@@ -0,0 +1,30 @@
+import { OfficeFileType, OfficeDocumentCategory, OfficeBadgeMeta, OfficeDocumentInfo } from './types';
+/**
+ * Detects whether a string URL, File, or Blob represents a supported Microsoft Office document.
+ */
+export declare function getOfficeFileType(target: unknown): OfficeFileType | null;
+/**
+ * Returns true if the given input is a supported Microsoft Office document.
+ */
+export declare function isOfficeDocument(target: unknown): boolean;
+/**
+ * Returns the broad document category ('word' | 'powerpoint' | 'excel') for an Office file type.
+ */
+export declare function getOfficeDocumentCategory(fileType: OfficeFileType): OfficeDocumentCategory;
+/**
+ * Returns standard MIME type for an Office file type.
+ */
+export declare function getOfficeMimeType(fileType: OfficeFileType): string;
+/**
+ * Metadata used to display themed UI badges, spinners, and icons for Office document types.
+ */
+export declare function getOfficeBadgeMeta(fileType: OfficeFileType): OfficeBadgeMeta;
+/**
+ * Inspects a target and returns rich Office metadata if it is an Office document.
+ */
+export declare function getOfficeDocumentInfo(target: unknown): OfficeDocumentInfo | null;
+export declare const isOfficeDocumentUrl: typeof isOfficeDocument;
+export declare const isOfficeFile: typeof isOfficeDocument;
+export declare const detectOfficeType: typeof getOfficeFileType;
+export declare function isOfficeExtension(ext: string): boolean;
+export declare const SUPPORTED_OFFICE_EXTENSIONS: readonly ["docx", "doc", "pptx", "ppt", "xlsx", "xls"];

package/dist/src/office/types.d.ts

@@ -0,0 +1,67 @@
+export type OfficeFileType = 'docx' | 'doc' | 'pptx' | 'ppt' | 'xlsx' | 'xls';
+export type OfficeDocumentCategory = 'word' | 'powerpoint' | 'excel';
+export interface OfficeBadgeMeta {
+    category: OfficeDocumentCategory;
+    name: string;
+    extension: string;
+    brandColor: string;
+    darkBrandColor: string;
+    iconName: string;
+}
+export type OfficeConversionState = 'idle' | 'converting' | 'converted' | 'error';
+export interface OfficeConverterConfig {
+    /**
+     * Backend conversion endpoint URL (e.g. Gotenberg, custom API proxy, or serverless function).
+     * Example: 'http://localhost:3000/api/convert-office' or 'http://localhost:3001/forms/libreoffice/convert'
+     */
+    endpoint?: string;
+    /**
+     * Custom HTTP headers to include with the conversion request.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Authorization token (Bearer token, API key, or JWT) sent with conversion requests.
+     * Can be a static string or a function/promise returning the current token.
+     * Automatically injected as 'Authorization: Bearer <token>' header.
+     */
+    authToken?: string | (() => string | Promise<string>);
+    /**
+     * Caching strategy:
+     * - 'memory': Cache converted PDF ArrayBuffers in browser memory for the current session (default).
+     * - 'session': Cache in sessionStorage.
+     * - 'none': Do not cache.
+     */
+    cache?: 'memory' | 'session' | 'none' | boolean;
+    /**
+     * Custom conversion hook allowing host application to supply its own conversion logic.
+     * If provided, this hook is called instead of the built-in Gotenberg/HTTP dispatcher.
+     */
+    convert?: (fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, options?: {
+        fileName?: string;
+        excelOptions?: OfficeConverterConfig['excelOptions'];
+    }) => Promise<ArrayBuffer | Uint8Array | Blob | string>;
+    /**
+     * Options for Excel worksheet conversion.
+     */
+    excelOptions?: {
+        fitToPageWidth?: boolean;
+        includeGridlines?: boolean;
+        paperSize?: 'A4' | 'Letter' | 'Legal';
+        orientation?: 'landscape' | 'portrait';
+    };
+}
+export interface OfficeDocumentInfo {
+    fileType: OfficeFileType;
+    category: OfficeDocumentCategory;
+    fileName?: string;
+    originalUrl?: string;
+    mimeType: string;
+}
+/**
+ * Alias for OfficeConverterConfig for ergonomic naming.
+ */
+export type OfficeConversionConfig = OfficeConverterConfig;
+/**
+ * Alias for OfficeDocumentInfo / options.
+ */
+export type OfficeDocumentOptions = OfficeDocumentInfo;

package/dist/src/office/useOfficeDocument.d.ts

@@ -0,0 +1,44 @@
+import { OfficeConverterConfig, OfficeFileType, OfficeDocumentInfo } from './types';
+export interface UseOfficeDocumentOptions {
+    /** Converter configuration (endpoint, authToken, cache mode, etc.) */
+    converterConfig?: OfficeConverterConfig;
+    /** Optional file name override */
+    fileName?: string;
+    /** Whether to automatically convert when the document changes (defaults to true) */
+    autoConvert?: boolean;
+}
+export interface UseOfficeDocumentResult {
+    /** Whether the input source was identified as a Microsoft Office document */
+    isOffice: boolean;
+    /** Detected office file type ('docx', 'pptx', 'xlsx', etc.) or null if PDF */
+    fileType: OfficeFileType | null;
+    /** Detailed metadata about the office document */
+    documentInfo: OfficeDocumentInfo | null;
+    /** Whether conversion is actively in progress */
+    isConverting: boolean;
+    /** The final PDF URL ready for the viewer (<TeamSyncViewer fileUrl={pdfUrl} />) */
+    pdfUrl: string | null;
+    /** Raw PDF ArrayBuffer */
+    pdfBuffer: ArrayBuffer | null;
+    /** Whether the document was served from memory/session cache */
+    fromCache: boolean;
+    /** Any error encountered during conversion */
+    error: Error | null;
+    /** Manually trigger conversion or retry */
+    convert: () => Promise<string | null>;
+}
+/**
+ * React hook that pre-converts Office documents into viewable PDF URLs before viewer mounting.
+ * If the input is already a PDF, it passes through immediately with `isConverting: false`.
+ */
+export declare function useOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer | null | undefined, options?: UseOfficeDocumentOptions): UseOfficeDocumentResult;
+/**
+ * Standalone asynchronous preloader for Office documents.
+ * Can be called anywhere (e.g. in loaders, event handlers, or background tasks).
+ */
+export declare function preloadOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer, config: OfficeConverterConfig, fileName?: string): Promise<{
+    pdfUrl: string;
+    pdfBuffer: ArrayBuffer;
+    fromCache: boolean;
+    fileType: OfficeFileType | 'pdf';
+}>;

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;