@dtducas/wh-forge-viewer 1.0.8-beta → 2.0.0-beta.1

package/dist/index.d.ts

@@ -3,7 +3,7 @@
 // Definitions by: Duong Tran Quang <https://github.com/DTDucas>
 /// <reference types="react" />
 declare module '@dtducas/wh-forge-viewer' {
-  import { FC } from 'react';
+  import type { ReactElement, ReactNode } from 'react';
   /**
    * Supported file extensions for the Forge Viewer
    */
@@ -43,6 +43,10 @@ declare module '@dtducas/wh-forge-viewer' {
         setTool(toolName: string): void;
         toolbar: any;
         model: any;
+        /** The WebGL canvas element used for rendering */
+        canvas: HTMLCanvasElement;
+        /** The viewer's DOM container element */
+        container: HTMLElement;
       }
       export interface Extension {
         load(): boolean;
@@ -54,6 +58,382 @@ declare module '@dtducas/wh-forge-viewer' {
       export const TOOLBAR_CREATED_EVENT: string;
     }
   }
+  // ========================================
+  // Drawing Types
+  // ========================================
+
+  /**
+   * Supported markup tool types
+   */
+  export type TMarkupToolType =
+    | 'arrow'
+    | 'rectangle'
+    | 'ellipse'  // Circle tool
+    | 'cloud'
+    | 'label'    // Text tool
+    | 'freehand' // Pen tool
+    | 'line'
+    | 'polyline'
+    | 'polycloud'
+    | 'callout'
+    | 'image';   // Image/Stamp tool
+
+  /**
+   * Markup style configuration
+   */
+  export interface IMarkupStyle {
+    strokeColor: string;
+    strokeWidth: number;
+    strokeOpacity: number;
+    fillColor: string;
+    fillOpacity: number;
+  }
+
+  /**
+   * Markup data structure
+   */
+  export interface IMarkupData {
+    version: string;
+    markups: any[];
+    metadata?: {
+      createdAt: string;
+      modifiedAt: string;
+    };
+  }
+
+  /**
+   * DrawingManager configuration
+   */
+  export interface IDrawingManagerConfig {
+    autoEnterEditMode?: boolean;
+    defaultTool?: TMarkupToolType;
+    defaultStyles?: Partial<IMarkupStyle>;
+  }
+
+  /**
+   * MarkupToolbar component props
+   */
+  export interface IMarkupToolbarProps {
+    drawingManager: DrawingManager;
+    onClose?: () => void;
+    position?: 'top' | 'bottom';
+    theme?: 'light' | 'dark';
+  }
+
+  // ========================================
+  // Property Panel Types
+  // ========================================
+
+  /**
+   * Property control types
+   */
+  export type TPropertyControlType =
+    | 'color'
+    | 'slider'
+    | 'select'
+    | 'button-group'
+    | 'toggle'
+    | 'action-button';
+
+  /**
+   * Property value types
+   */
+  export type TPropertyValue = string | number | boolean;
+
+  /**
+   * Property option for select/button-group controls
+   */
+  export interface IPropertyOption {
+    value: string | number;
+    label: string;
+    icon?: ReactNode;
+    tooltip?: string;
+  }
+
+  /**
+   * Base property definition
+   */
+  export interface IPropertyDefinition {
+    key: string;
+    label: string;
+    controlType: TPropertyControlType;
+    defaultValue: TPropertyValue;
+    category: 'stroke' | 'fill' | 'style' | 'text' | 'layer' | 'action';
+    tooltip?: string;
+  }
+
+  /**
+   * Color property
+   */
+  export interface IColorProperty extends IPropertyDefinition {
+    controlType: 'color';
+    defaultValue: string;
+    presetColors?: string[];
+  }
+
+  /**
+   * Slider property
+   */
+  export interface ISliderProperty extends IPropertyDefinition {
+    controlType: 'slider';
+    defaultValue: number;
+    min: number;
+    max: number;
+    step: number;
+    marks?: Record<number, string>;
+  }
+
+  /**
+   * Select property
+   */
+  export interface ISelectProperty extends IPropertyDefinition {
+    controlType: 'select';
+    defaultValue: string | number;
+    options: IPropertyOption[];
+  }
+
+  /**
+   * Button group property
+   */
+  export interface IButtonGroupProperty extends IPropertyDefinition {
+    controlType: 'button-group';
+    defaultValue: string | number;
+    options: IPropertyOption[];
+    exclusive?: boolean;
+  }
+
+  /**
+   * Toggle property
+   */
+  export interface IToggleProperty extends IPropertyDefinition {
+    controlType: 'toggle';
+    defaultValue: boolean;
+  }
+
+  /**
+   * Action button property
+   */
+  export interface IActionButtonProperty extends IPropertyDefinition {
+    controlType: 'action-button';
+    defaultValue: never;
+    action: string;
+    icon?: ReactNode;
+    variant?: 'default' | 'danger' | 'primary';
+  }
+
+  /**
+   * Union type of all property types
+   */
+  export type TProperty =
+    | IColorProperty
+    | ISliderProperty
+    | ISelectProperty
+    | IButtonGroupProperty
+    | IToggleProperty
+    | IActionButtonProperty;
+
+  /**
+   * Tool property configuration
+   */
+  export interface IToolPropertyConfig {
+    toolType: TMarkupToolType;
+    displayName: string;
+    properties: TProperty[];
+    onPropertyChange?: (key: string, value: TPropertyValue) => void;
+    onAction?: (action: string) => void;
+  }
+
+  /**
+   * PropertyPanel component props
+   */
+  export interface IPropertyPanelProps {
+    config: IToolPropertyConfig | null;
+    values: Record<string, TPropertyValue>;
+    onPropertyChange: (key: string, value: TPropertyValue) => void;
+    onAction: (action: string) => void;
+    visible?: boolean;
+    position?: 'left' | 'right';
+    theme?: 'light' | 'dark';
+  }
+
+  /**
+   * DrawingManager class
+   * Manages Forge Viewer markup functionality
+   */
+  export class DrawingManager {
+    constructor(
+      viewer: Autodesk.Viewing.GuiViewer3D,
+      eventBus: any,
+      config?: IDrawingManagerConfig
+    );
+    enterEditMode(): Promise<void>;
+    leaveEditMode(): void;
+    isEditMode(): boolean;
+    setActiveTool(toolType: TMarkupToolType): void;
+    getActiveTool(): TMarkupToolType | null;
+    setStrokeStyle(color: string, width: number, opacity: number): void;
+    setFillStyle(color: string, opacity: number): void;
+    saveMarkups(): IMarkupData;
+    loadMarkups(data: IMarkupData): void;
+    clearMarkups(): void;
+    exportToSVG(): string;
+    undo(): void;
+    redo(): void;
+    getCurrentStyles(): IMarkupStyle;
+    getCurrentToolPropertyConfig(): IToolPropertyConfig | null;
+    handlePropertyChange(key: string, value: any): void;
+    handleAction(action: string): void;
+    destroy(): void;
+
+    // Collaborative Markup API
+    getMarkupData(viewableGUID: string): IMarkupDataExport;
+    loadMarkupData(data: IMarkupDataExport, options?: ILoadMarkupDataOptions): Promise<void>;
+    onMarkupChange(callback: OnMarkupChangeCallback): () => void;
+    applyDelta(delta: IMarkupDelta & { compactElement?: IMarkupElementCompact }): boolean;
+    applyBatch(elements: IMarkupElementCompact[], clearExisting?: boolean): number;
+    getMarkupSVG(): string;
+
+    // Real-time Collaboration Rendering APIs
+    renderFromSVG(svgString: string, options?: { clearExisting?: boolean; layerId?: string }): number;
+    mergeFromSVG(svgString: string, layerId?: string): number;
+    clearForPageChange(viewableGUID: string): IMarkupDataExport;
+    restoreAfterPageChange(data: IMarkupDataExport, options?: ILoadMarkupDataOptions): Promise<void>;
+
+    // SVG/JSON Conversion APIs
+    getMarkupDataAsJson(viewableGUID: string): IJsonMarkupData;
+    loadMarkupDataFromJson(jsonData: IJsonMarkupData, options?: ILoadMarkupDataOptions): Promise<void>;
+
+    // PDF Export API
+    exportPDFWithMarkup(pdfSource: Blob | string, markupsByPage: IPageMarkupData[], options?: IExportPdfOptions): Promise<IExportResult>;
+    exportAndDownloadPDF(pdfSource: Blob | string, markupsByPage: IPageMarkupData[], options?: IExportPdfOptions): Promise<boolean>;
+    exportCurrentPagePDF(pdfSource: Blob | string, pageIndex?: number, options?: IExportPdfOptions): Promise<IExportResult>;
+
+    // User Presence API
+    updateUserCursor(cursor: IUserCursor): void;
+    removeUserCursor(userId: string): void;
+    getRemoteCursors(): Map<string, IUserCursor>;
+    onLocalCursorMove(callback: OnLocalCursorMoveCallback): () => void;
+    clearAllCursors(): void;
+  }
+
+  /**
+   * MarkupToolbar component
+   */
+  export function MarkupToolbar(props: IMarkupToolbarProps): JSX.Element;
+
+  /**
+   * PropertyPanel component
+   */
+  export function PropertyPanel(props: IPropertyPanelProps): JSX.Element;
+
+  /**
+   * Markup tool constants
+   */
+  export const MARKUP_TOOLS: {
+    ARROW: 'arrow';
+    RECTANGLE: 'rectangle';
+    CIRCLE: 'ellipse';
+    CLOUD: 'cloud';
+    TEXT: 'label';
+    PEN: 'freehand';
+    /** @deprecated Use PEN instead */
+    FREEHAND: 'freehand';
+    LINE: 'line';
+    POLYLINE: 'polyline';
+    POLYCLOUD: 'polycloud';
+    CALLOUT: 'callout';
+    IMAGE: 'image';
+  };
+
+  /**
+   * Default markup styles
+   */
+  export const DEFAULT_MARKUP_STYLES: IMarkupStyle;
+
+  /**
+   * Preset colors
+   */
+  export const PRESET_COLORS: readonly string[];
+
+  // ========================================
+  // Markup Tools (OOP Architecture)
+  // ========================================
+
+  /**
+   * Abstract base class for all markup tools
+   */
+  export abstract class MarkupTool {
+    constructor(markupsCore: any);
+    getToolId(): string;
+    getEditModeClassName(): string;
+    getDisplayName(): string;
+    activate(styles?: IMarkupStyle): void;
+    deactivate(): void;
+    supportsFillColor(): boolean;
+    getMetadata(): Record<string, any>;
+    getPropertyConfig(): IToolPropertyConfig | null;
+    onPropertyChange(key: string, value: any): void;
+    onAction(action: string): void;
+  }
+
+  /**
+   * Concrete tool implementations
+   */
+  export class ArrowTool extends MarkupTool {}
+  export class RectangleTool extends MarkupTool {}
+  export class CircleTool extends MarkupTool {}
+  export class CloudTool extends MarkupTool {}
+  export class TextTool extends MarkupTool {}
+  export class FreehandTool extends MarkupTool {}
+  /** Alias for FreehandTool */
+  export class PenTool extends MarkupTool {}
+  export class LineTool extends MarkupTool {}
+  export class PolylineTool extends MarkupTool {}
+  export class PolycloudTool extends MarkupTool {}
+  export class CalloutTool extends MarkupTool {}
+  export class ImageTool extends MarkupTool {
+    setImage(imageData: string, width: number, height: number, type?: 'base64' | 'svg'): void;
+    getPendingImage(): { data: string; width: number; height: number; type: 'base64' | 'svg'; storageId?: string } | null;
+    clearPendingImage(): void;
+    loadImageFile(file: File, options?: { storeInIndexedDB?: boolean }): Promise<string | void>;
+    loadSVGFile(file: File): Promise<void>;
+    // IndexedDB Storage Methods
+    initializeStorage(): Promise<void>;
+    getStorageService(): ImageStorageService | null;
+    storeImage(imageData: string, metadata?: { fileName?: string; mimeType?: string; width?: number; height?: number }): Promise<string>;
+    getStoredImage(storageId: string): Promise<string | null>;
+    hasStoredImage(storageId: string): Promise<boolean>;
+    deleteStoredImage(storageId: string): Promise<boolean>;
+    getCurrentStorageId(): string;
+    loadFromStorage(storageId: string): Promise<void>;
+  }
+
+  /**
+   * Tool Factory for creating tool instances
+   */
+  export class ToolFactory {
+    constructor(markupsCore: any);
+    createTool(toolType: TMarkupToolType): MarkupTool | null;
+    getAvailableTools(): TMarkupToolType[];
+    static registerCustomTool(toolType: TMarkupToolType, toolClass: any): void;
+    clearInstances(): void;
+    getToolInstance(toolType: TMarkupToolType): MarkupTool | undefined;
+  }
+
+  /**
+   * Tool Registry for managing tool types
+   */
+  export class ToolRegistry {
+    static registerTool(toolType: TMarkupToolType, toolClass: any): void;
+    static getToolConstructor(toolType: TMarkupToolType): any;
+    static getAllToolTypes(): TMarkupToolType[];
+    static hasToolType(toolType: TMarkupToolType): boolean;
+  }
+
+  // ========================================
+  // Viewer Component Props
+  // ========================================
+
   /**
    * Props for ViewerForgePDF component
    */
@@ -75,6 +455,15 @@ declare module '@dtducas/wh-forge-viewer' {
      * Callback to receive viewer instance when initialized
      */
     setViewer?: (viewer: Autodesk.Viewing.GuiViewer3D | null) => void;
+    /**
+     * Enable custom markup toolbar
+     * @default false
+     */
+    enableCustomMarkups?: boolean;
+    /**
+     * Configuration for DrawingManager
+     */
+    markupConfig?: IDrawingManagerConfig;
   }
   /**
    * ViewerForgePDF - React component for displaying PDF and CAD files using Autodesk Forge Viewer
@@ -97,5 +486,652 @@ declare module '@dtducas/wh-forge-viewer' {
    * }
    * ```
    */
-  export const ViewerForgePDF: FC<IViewerForgePDFProps>;
+  export function ViewerForgePDF(props: IViewerForgePDFProps): JSX.Element;
+
+  // ========================================
+  // EventBus for page change events
+  // ========================================
+
+  /**
+   * Event names for EventBus subscriptions
+   */
+  export const EVENT_NAMES: {
+    PAGE_CHANGING: 'page:changing';
+    PAGE_CHANGED: 'page:changed';
+    VIEWABLES_SET: 'viewables:set';
+    DOC_BROWSER_OPENED: 'docBrowser:opened';
+    DOC_BROWSER_CLOSED: 'docBrowser:closed';
+    MARKUP_CHANGED: 'markup:changed';
+  };
+
+  /**
+   * EventBus singleton for cross-component communication
+   */
+  export class EventBus {
+    static getInstance(): EventBus;
+    on(event: string, callback: (...args: any[]) => void): void;
+    off(event: string, callback: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+    once(event: string, callback: (...args: any[]) => void): void;
+  }
+
+  // ========================================
+  // Collaborative Markup API Types
+  // ========================================
+
+  /**
+   * Individual markup item
+   */
+  export interface IMarkupItem {
+    id: string;
+    type: string;
+    position: { x: number; y: number };
+    size: { x: number; y: number };
+    rotation: number;
+    style: Record<string, any>;
+  }
+
+  /**
+   * Markup data export format for persistence
+   */
+  export interface IMarkupDataExport {
+    version: string;
+    /** Viewable identifier - provided by the consuming app (any string format) */
+    viewableGUID: string;
+    svgString: string;
+    markups: IMarkupItem[];
+    timestamp: number;
+  }
+
+  /**
+   * Markup change delta for real-time sync
+   */
+  export interface IMarkupDelta {
+    type: 'create' | 'update' | 'delete';
+    markupId: string;
+    data?: Partial<IMarkupItem>;
+    timestamp: number;
+    /** Compact element for JSON-based sync (attached when using serializer) */
+    compactElement?: IMarkupElementCompact;
+  }
+
+  // ========================================
+  // JSON-based Sync Types (Compact Format)
+  // ========================================
+
+  /**
+   * Compact markup element format for real-time sync
+   * ~80 bytes vs ~500 bytes for SVG strings
+   */
+  export interface IMarkupElementCompact {
+    /** Unique markup ID */
+    id: string;
+    /** Markup type */
+    type: string;
+    /** Position in markup coordinates [x, y] */
+    pos: [number, number];
+    /** Size in markup coordinates [width, height] */
+    size: [number, number];
+    /** Rotation in radians */
+    rot: number;
+    /** Style properties (compact keys) */
+    style: ICompactStyle;
+    /** Shape-specific data */
+    shape?: IShapeData;
+    /** Version number for CRDT conflict resolution */
+    version: number;
+    /** Tombstone flag for deletion */
+    deleted?: boolean;
+    /** Timestamp (Unix epoch ms) */
+    ts: number;
+    /** Created by user ID */
+    createdBy?: string;
+    /** Modified by user ID */
+    modifiedBy?: string;
+  }
+
+  /**
+   * Compact style properties (short keys for minimal payload)
+   */
+  export interface ICompactStyle {
+    /** Stroke color (hex) */
+    sc?: string;
+    /** Stroke width */
+    sw?: number;
+    /** Stroke opacity (0-1) */
+    so?: number;
+    /** Stroke dash array */
+    sd?: string;
+    /** Fill color (hex) */
+    fc?: string;
+    /** Fill opacity (0-1) */
+    fo?: number;
+    /** Font size */
+    fs?: number;
+    /** Font family */
+    ff?: string;
+    /** Font weight */
+    fw?: string;
+    /** Font style */
+    fi?: string;
+  }
+
+  /**
+   * Shape-specific data for different markup types
+   */
+  export interface IShapeData {
+    /** Points array (flat: [x1,y1,x2,y2,...]) */
+    points?: number[];
+    /** Text content */
+    text?: string;
+    /** Image data URI */
+    imageData?: string;
+    /** Cloud arc count */
+    arcCount?: number;
+    /** Path data string */
+    pathData?: string;
+    /** Arrow head configuration */
+    head?: { type: string; size: number };
+    /** Arrow tail configuration */
+    tail?: { type: string; size: number };
+  }
+
+  /**
+   * Serialize a Forge Markup object to compact JSON format
+   */
+  export function serializeMarkup(
+    markup: any,
+    userId?: string
+  ): IMarkupElementCompact | null;
+
+  /**
+   * Deserialize compact style to Forge-compatible style object
+   */
+  export function deserializeStyle(compact: ICompactStyle): Record<string, any>;
+
+  /**
+   * Expand flat points array to {x, y} objects
+   */
+  export function expandPoints(flatPoints: number[]): Array<{ x: number; y: number }>;
+
+  /**
+   * Calculate byte size of serialized markup
+   */
+  export function getSerializedSize(compact: IMarkupElementCompact): number;
+
+  /**
+   * Render a compact markup element to the Forge Viewer canvas
+   */
+  export function renderMarkupElement(
+    element: IMarkupElementCompact,
+    markupsCore: any,
+    mode?: 'create' | 'update'
+  ): boolean;
+
+  /**
+   * Delete a markup element from the canvas
+   */
+  export function deleteMarkupElement(
+    elementId: string,
+    markupsCore: any
+  ): boolean;
+
+  /**
+   * Render multiple markup elements as a batch
+   */
+  export function renderMarkupBatch(
+    elements: IMarkupElementCompact[],
+    markupsCore: any,
+    clearExisting?: boolean
+  ): number;
+
+  /**
+   * Clear all markups from the canvas
+   */
+  export function clearAllMarkups(markupsCore: any): void;
+
+  /**
+   * Options for loadMarkupData method
+   */
+  export interface ILoadMarkupDataOptions {
+    mode?: 'replace' | 'merge';
+  }
+
+  /**
+   * Callback type for markup change subscription
+   */
+  export type OnMarkupChangeCallback = (delta: IMarkupDelta) => void;
+
+  // ========================================
+  // User Presence API Types
+  // ========================================
+
+  /**
+   * User cursor data for collaborative presence
+   */
+  export interface IUserCursor {
+    userId: string;
+    userName: string;
+    color: string;
+    position: { x: number; y: number };
+    timestamp: number;
+  }
+
+  /**
+   * Callback for local cursor movement
+   */
+  export type OnLocalCursorMoveCallback = (payload: {
+    position: { x: number; y: number };
+    screenPosition: { x: number; y: number };
+    timestamp: number;
+  }) => void;
+
+  /**
+   * CursorOverlay component props
+   */
+  export interface ICursorOverlayProps {
+    cursors: Map<string, IUserCursor>;
+    containerRef?: React.RefObject<HTMLElement>;
+  }
+
+  /**
+   * CursorOverlay component for displaying remote user cursors
+   */
+  export function CursorOverlay(props: ICursorOverlayProps): JSX.Element;
+
+  // ========================================
+  // PDF Export Services
+  // ========================================
+
+  /**
+   * Export options for PDF with markup
+   */
+  export interface IExportPdfOptions {
+    /** Output filename without extension @default 'document-with-markup' */
+    filename?: string;
+    /** Preserve original PDF metadata @default true */
+    preserveMetadata?: boolean;
+    /** Flatten markups (cannot be edited later) @default true */
+    flattenMarkups?: boolean;
+  }
+
+  /**
+   * Markup data for a single page
+   */
+  export interface IPageMarkupData {
+    /** Page index (0-based) */
+    pageIndex: number;
+    /** SVG string of markups for this page */
+    svgString: string;
+    /** SVG viewBox dimensions (extracted from SVG if not provided) */
+    viewBox?: { x: number; y: number; width: number; height: number };
+    /** Model bounding box from Forge Viewer (PDF page extent in viewer coords) */
+    modelBounds?: { minX: number; minY: number; maxX: number; maxY: number };
+  }
+
+  /**
+   * Export result
+   */
+  export interface IExportResult {
+    /** Whether export was successful */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Resulting PDF blob */
+    blob?: Blob;
+    /** Number of pages processed */
+    pagesProcessed: number;
+  }
+
+  /**
+   * Conversion options for SVG to PDF
+   */
+  export interface ISvgToPdfOptions {
+    /** PDF page width in points */
+    pageWidth: number;
+    /** PDF page height in points */
+    pageHeight: number;
+    /** SVG viewBox dimensions */
+    svgViewBox: { x: number; y: number; width: number; height: number };
+    /** Model bounding box (PDF page extent in viewer coords) - used instead of viewBox for mapping */
+    modelBounds?: { minX: number; minY: number; maxX: number; maxY: number };
+    /** Scale factor @default 1 */
+    scale?: number;
+    /** Offset for positioning */
+    offset?: { x: number; y: number };
+  }
+
+  /**
+   * Service for exporting PDF with markup overlaid as vector graphics
+   * Uses pdf-lib and SvgToPdfConverter for client-side PDF manipulation
+   *
+   * @example
+   * ```typescript
+   * const exportService = new MarkupExportService();
+   * const result = await exportService.exportPDFWithMarkup(
+   *   pdfBlob,
+   *   [{ pageIndex: 0, svgString: svgMarkup }],
+   *   { filename: 'annotated-document' }
+   * );
+   * ```
+   */
+  export class MarkupExportService {
+    constructor();
+    exportPDFWithMarkup(originalPdfBlob: Blob, markupsByPage: IPageMarkupData[], options?: IExportPdfOptions): Promise<IExportResult>;
+    exportPDFWithMarkupMap(originalPdfBlob: Blob, markupsByPage: Map<number, string>, options?: IExportPdfOptions): Promise<IExportResult>;
+    exportAndDownload(originalPdfBlob: Blob, markupsByPage: IPageMarkupData[], options?: IExportPdfOptions): Promise<boolean>;
+    downloadPdf(blob: Blob, filename?: string): void;
+    static fetchPdfBlob(pdfSource: Blob | string): Promise<Blob>;
+  }
+
+  /**
+   * SVG to PDF Converter
+   * Converts SVG markup elements to PDF drawing operations using pdf-lib
+   *
+   * @example
+   * ```typescript
+   * const converter = new SvgToPdfConverter();
+   * await converter.drawSvgOnPdfPage(svgString, pdfPage, {
+   *   pageWidth: 612, pageHeight: 792,
+   *   svgViewBox: { x: 0, y: 0, width: 1000, height: 1000 }
+   * });
+   * ```
+   */
+  export class SvgToPdfConverter {
+    drawSvgOnPdfPage(svgString: string, pdfPage: any, options: ISvgToPdfOptions): Promise<void>;
+  }
+
+  // ========================================
+  // Toolbar Visibility API Types
+  // ========================================
+
+  /**
+   * Toolbar button identifiers
+   */
+  export type TToolbarButtonId = 'pan' | 'docBrowser' | 'download' | 'markup' | 'pagination';
+
+  /**
+   * Toolbar button visibility configuration
+   */
+  export interface IToolbarVisibilityConfig {
+    pan?: boolean;
+    docBrowser?: boolean;
+    download?: boolean;
+    markup?: boolean;
+    pagination?: boolean;
+  }
+
+  /**
+   * Toolbar visibility API interface
+   */
+  export interface IToolbarVisibilityAPI {
+    getVisibilityConfig(): IToolbarVisibilityConfig;
+    setVisibilityConfig(config: IToolbarVisibilityConfig): void;
+    showButton(buttonId: TToolbarButtonId): void;
+    hideButton(buttonId: TToolbarButtonId): void;
+    showAllButtons(): void;
+    hideAllButtons(): void;
+    isButtonVisible(buttonId: TToolbarButtonId): boolean;
+  }
+
+  /**
+   * Default toolbar visibility configuration (all visible)
+   */
+  export const DEFAULT_TOOLBAR_VISIBILITY: Required<IToolbarVisibilityConfig>;
+
+  // ========================================
+  // Image Storage Service (IndexedDB)
+  // ========================================
+
+  /**
+   * Stored image data structure
+   */
+  export interface IStoredImage {
+    id: string;
+    data: string;
+    mimeType: string;
+    fileName?: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    createdAt: number;
+    lastAccessedAt: number;
+    expiresAt?: number;
+  }
+
+  /**
+   * Image storage configuration
+   */
+  export interface IImageStorageConfig {
+    dbName?: string;
+    maxStorageSize?: number;
+    defaultExpiryMs?: number;
+    enableAutoCleanup?: boolean;
+    cleanupIntervalMs?: number;
+  }
+
+  /**
+   * Storage statistics
+   */
+  export interface IStorageStats {
+    totalImages: number;
+    totalSizeBytes: number;
+    oldestImage?: number;
+    newestImage?: number;
+    expiredCount: number;
+  }
+
+  /**
+   * Image storage service using IndexedDB
+   */
+  export class ImageStorageService {
+    static getInstance(config?: IImageStorageConfig): ImageStorageService;
+    initialize(): Promise<void>;
+    storeImage(imageData: string, metadata?: Partial<IStoredImage>): Promise<string>;
+    getImage(id: string): Promise<IStoredImage | null>;
+    hasImage(id: string): Promise<boolean>;
+    deleteImage(id: string): Promise<boolean>;
+    cleanupExpiredImages(): Promise<number>;
+    clearAll(): Promise<void>;
+    getStorageStats(): Promise<IStorageStats>;
+    destroy(): void;
+  }
+
+  // ========================================
+  // Markup Converter Service (SVG ↔ JSON)
+  // ========================================
+
+  /**
+   * JSON markup data format for database storage
+   * Coordinates are stored as-is (no scaling)
+   */
+  export interface IJsonMarkupData {
+    /** Format version for JSON schema compatibility */
+    version: string;
+    /** Viewable identifier - provided by the consuming app (any string format) */
+    viewableGUID: string;
+    /** Array of compact markup elements */
+    elements: IMarkupElementCompact[];
+    /** Optional metadata for custom data */
+    metadata?: Record<string, any>;
+    /** Timestamp when data was created (Unix epoch ms) */
+    timestamp: number;
+  }
+
+  /**
+   * SVG validation result
+   */
+  export interface ISvgValidationResult {
+    valid: boolean;
+    errors: string[];
+    markupCount: number;
+  }
+
+  /**
+   * JSON validation result
+   */
+  export interface IJsonValidationResult {
+    valid: boolean;
+    errors: string[];
+  }
+
+  /**
+   * Service for converting between SVG and JSON markup formats
+   *
+   * ID FORMAT:
+   * Element IDs use compact format: {toolCode}-{timestamp}-{random4}
+   * Example: "1-1770285843573-a7f3" (freehand=1)
+   *
+   * @example
+   * ```typescript
+   * // SVG to JSON
+   * const svg = markupsCore.generateData();
+   * const json = MarkupConverterService.svgToJson(svg, 'my-page-id');
+   *
+   * // JSON to SVG (for restoring)
+   * const svg = MarkupConverterService.jsonToSvg(json);
+   * markupsCore.loadMarkups(svg, 'restored-layer');
+   * ```
+   */
+  export class MarkupConverterService {
+    static svgToJson(svgString: string, viewableGUID: string): IJsonMarkupData;
+    static jsonToSvg(jsonData: IJsonMarkupData, layerId?: string): string;
+    static validateJsonData(data: unknown): IJsonValidationResult;
+    static validateSvgString(svgString: string): ISvgValidationResult;
+    static isValidJsonData(data: unknown): data is IJsonMarkupData;
+    static getCurrentVersion(): string;
+    static isVersionCompatible(version: string): boolean;
+    static mergeJsonData(dataSets: IJsonMarkupData[]): IJsonMarkupData;
+  }
+
+  /**
+   * Generate UUIDv7 - time-ordered UUID
+   * Utility function, can be used if you need a UUID identifier
+   * Note: viewableGUID can be any string, UUIDv7 is not required
+   *
+   * @example
+   * ```typescript
+   * const id = generateUUIDv7();
+   * // "0192d4e5-7f8a-7b3c-9d1e-2f4a6b8c0d2e"
+   * ```
+   */
+  export function generateUUIDv7(): string;
+
+  /**
+   * Validate if a string is a valid UUID format (v4 or v7)
+   * Format: xxxxxxxx-xxxx-Vxxx-yxxx-xxxxxxxxxxxx
+   *
+   * @param uuid - String to validate
+   * @returns True if valid UUID format
+   *
+   * @example
+   * ```typescript
+   * isValidUUID('0192d4e5-7f8a-7b3c-9d1e-2f4a6b8c0d2e'); // true
+   * isValidUUID('test-viewable-guid'); // false
+   * ```
+   */
+  export function isValidUUID(uuid: string): boolean;
+
+  /**
+   * Validate if a string is a valid UUIDv7 format
+   * Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+   * Version 7 indicated by '7' at position 14
+   *
+   * @param uuid - String to validate
+   * @returns True if valid UUIDv7 format
+   *
+   * @example
+   * ```typescript
+   * isValidUUIDv7('0192d4e5-7f8a-7b3c-9d1e-2f4a6b8c0d2e'); // true (if version is 7)
+   * isValidUUIDv7('550e8400-e29b-41d4-a716-446655440000'); // false (version 4)
+   * ```
+   */
+  export function isValidUUIDv7(uuid: string): boolean;
+
+  /**
+   * Coordinate scale factor for precision calculations (1e7)
+   * Use this constant when performing math operations that need precision
+   * Note: Coordinates are NOT scaled in storage
+   */
+  export const MARKUP_COORDINATE_SCALE: number;
+
+  /**
+   * Tool type to numeric code mapping for compact ID generation
+   * Used in element ID format: {toolCode}-{timestamp}-{random4}
+   */
+  export const MARKUP_TOOL_CODES: Record<string, number>;
+
+  // ========================================
+  // Coordinate System Utilities
+  // ========================================
+
+  /**
+   * Coordinate space types
+   */
+  export type TCoordinateSpace = 'screen' | 'markup' | 'page';
+
+  /**
+   * 2D point interface
+   */
+  export interface IPoint2D {
+    x: number;
+    y: number;
+  }
+
+  /**
+   * 2D bounds interface
+   */
+  export interface IBounds2D {
+    min: IPoint2D;
+    max: IPoint2D;
+  }
+
+  /**
+   * Coordinate validation result
+   */
+  export interface ICoordinateValidationResult {
+    valid: boolean;
+    space: TCoordinateSpace;
+    message?: string;
+    normalized?: IPoint2D;
+  }
+
+  /**
+   * Coordinate space information for debugging
+   */
+  export interface ICoordinateSpaceInfo {
+    viewBox: { x: number; y: number; width: number; height: number };
+    bounds: IBounds2D | null;
+    currentZoom: number;
+    currentPan: IPoint2D;
+    ctmMatrix: DOMMatrix | null;
+  }
+
+  /**
+   * Validate coordinates in markup space
+   */
+  export function validateMarkupCoordinates(
+    point: IPoint2D,
+    markupsCore: any
+  ): ICoordinateValidationResult;
+
+  /**
+   * Get coordinate space metadata for debugging
+   */
+  export function getCoordinateSpaceInfo(markupsCore: any): ICoordinateSpaceInfo;
+
+  /**
+   * Convert coordinates between different coordinate spaces
+   */
+  export function convertCoordinates(
+    point: IPoint2D,
+    from: TCoordinateSpace,
+    to: TCoordinateSpace,
+    markupsCore: any
+  ): IPoint2D;
+
+  /**
+   * Check if the coordinate system is normalized (zoom/pan independent)
+   */
+  export function isCoordinateSystemNormalized(markupsCore: any): boolean;
 }