@dtducas/wh-forge-viewer 2.0.0-beta.2 → 3.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 type { ReactElement, ReactNode } from 'react';
+  import type { ReactNode } from 'react';
   /**
    * Supported file extensions for the Forge Viewer
    */
@@ -68,15 +68,15 @@ declare module '@dtducas/wh-forge-viewer' {
   export type TMarkupToolType =
     | 'arrow'
     | 'rectangle'
-    | 'ellipse'  // Circle tool
+    | 'ellipse' // Circle tool
     | 'cloud'
-    | 'label'    // Text tool
+    | 'label' // Text tool
     | 'freehand' // Pen tool
     | 'line'
     | 'polyline'
     | 'polycloud'
     | 'callout'
-    | 'image';   // Image/Stamp tool
+    | 'image'; // Image/Stamp tool
 
   /**
    * Markup style configuration
@@ -264,7 +264,7 @@ declare module '@dtducas/wh-forge-viewer' {
     constructor(
       viewer: Autodesk.Viewing.GuiViewer3D,
       eventBus: any,
-      config?: IDrawingManagerConfig
+      config?: IDrawingManagerConfig,
     );
     enterEditMode(): Promise<void>;
     leaveEditMode(): void;
@@ -287,26 +287,47 @@ declare module '@dtducas/wh-forge-viewer' {
 
     // 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;
+    loadMarkupData(
+      data: IMarkupDataExport,
+      options?: ILoadMarkupDataOptions,
+    ): Promise<void>;
     getMarkupSVG(): string;
 
     // Real-time Collaboration Rendering APIs
-    renderFromSVG(svgString: string, options?: { clearExisting?: boolean; layerId?: string }): number;
+    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>;
+    restoreAfterPageChange(
+      data: IMarkupDataExport,
+      options?: ILoadMarkupDataOptions,
+    ): Promise<void>;
 
     // SVG/JSON Conversion APIs
     getMarkupDataAsJson(viewableGUID: string): IJsonMarkupData;
-    loadMarkupDataFromJson(jsonData: IJsonMarkupData, options?: ILoadMarkupDataOptions): Promise<void>;
+    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>;
+    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;
@@ -392,15 +413,37 @@ declare module '@dtducas/wh-forge-viewer' {
   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;
+    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>;
+    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>;
+    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>;
@@ -434,37 +477,6 @@ declare module '@dtducas/wh-forge-viewer' {
   // Viewer Component Props
   // ========================================
 
-  /**
-   * Props for ViewerForgePDF component
-   */
-  export interface IViewerForgePDFProps {
-    /**
-     * URL/path to the document to load
-     */
-    filePath: string;
-    /**
-     * File extension (pdf, dwf, dwfx, gltf, glb)
-     */
-    fileExt: TSupportedFileExtension;
-    /**
-     * Toolbar visibility options
-     * Controls which toolbar buttons and controls are displayed
-     */
-    toolbarOptions?: IToolbarOptions;
-    /**
-     * 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
    *
@@ -543,153 +555,6 @@ declare module '@dtducas/wh-forge-viewer' {
     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
    */
@@ -697,11 +562,6 @@ declare module '@dtducas/wh-forge-viewer' {
     mode?: 'replace' | 'merge';
   }
 
-  /**
-   * Callback type for markup change subscription
-   */
-  export type OnMarkupChangeCallback = (delta: IMarkupDelta) => void;
-
   // ========================================
   // User Presence API Types
   // ========================================
@@ -817,9 +677,21 @@ declare module '@dtducas/wh-forge-viewer' {
    */
   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>;
+    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>;
   }
@@ -838,7 +710,11 @@ declare module '@dtducas/wh-forge-viewer' {
    * ```
    */
   export class SvgToPdfConverter {
-    drawSvgOnPdfPage(svgString: string, pdfPage: any, options: ISvgToPdfOptions): Promise<void>;
+    drawSvgOnPdfPage(
+      svgString: string,
+      pdfPage: any,
+      options: ISvgToPdfOptions,
+    ): Promise<void>;
   }
 
   // ========================================
@@ -848,7 +724,12 @@ declare module '@dtducas/wh-forge-viewer' {
   /**
    * Toolbar button identifiers
    */
-  export type TToolbarButtonId = 'pan' | 'docBrowser' | 'download' | 'markup' | 'pagination';
+  export type TToolbarButtonId =
+    | 'pan'
+    | 'docBrowser'
+    | 'download'
+    | 'markup'
+    | 'pagination';
 
   /**
    * Toolbar button visibility configuration
@@ -927,7 +808,10 @@ declare module '@dtducas/wh-forge-viewer' {
   export class ImageStorageService {
     static getInstance(config?: IImageStorageConfig): ImageStorageService;
     initialize(): Promise<void>;
-    storeImage(imageData: string, metadata?: Partial<IStoredImage>): Promise<string>;
+    storeImage(
+      imageData: string,
+      metadata?: Partial<IStoredImage>,
+    ): Promise<string>;
     getImage(id: string): Promise<IStoredImage | null>;
     hasImage(id: string): Promise<boolean>;
     deleteImage(id: string): Promise<boolean>;
@@ -945,16 +829,12 @@ declare module '@dtducas/wh-forge-viewer' {
    * JSON markup data format for database storage
    * Coordinates are stored as-is (no scaling)
    */
+  /** @deprecated Use canvas-scene/2 (ICanvasMarkupSceneV2) for markup persistence. */
   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) */
+    elements: unknown[];
+    metadata?: Record<string, unknown>;
     timestamp: number;
   }
 
@@ -1112,13 +992,15 @@ declare module '@dtducas/wh-forge-viewer' {
    */
   export function validateMarkupCoordinates(
     point: IPoint2D,
-    markupsCore: any
+    markupsCore: any,
   ): ICoordinateValidationResult;
 
   /**
    * Get coordinate space metadata for debugging
    */
-  export function getCoordinateSpaceInfo(markupsCore: any): ICoordinateSpaceInfo;
+  export function getCoordinateSpaceInfo(
+    markupsCore: any,
+  ): ICoordinateSpaceInfo;
 
   /**
    * Convert coordinates between different coordinate spaces
@@ -1127,11 +1009,707 @@ declare module '@dtducas/wh-forge-viewer' {
     point: IPoint2D,
     from: TCoordinateSpace,
     to: TCoordinateSpace,
-    markupsCore: any
+    markupsCore: any,
   ): IPoint2D;
 
   /**
    * Check if the coordinate system is normalized (zoom/pan independent)
    */
   export function isCoordinateSystemNormalized(markupsCore: any): boolean;
+
+  // ========================================
+  // Advanced Features (v3.0.0)
+  // ========================================
+
+  // ── Markup Engine Adapter Pattern ──────────────────────────────────────────
+
+  /**
+   * Engine capabilities advertised by each IMarkupEngine implementation.
+   */
+  export interface IMarkupEngineCapabilities {
+    supportsCollaboration: boolean;
+    supportsBezierArcs: boolean;
+    supportsImages: boolean;
+    supportsExportPDF: boolean;
+    supportsImportSVG: boolean;
+  }
+
+  /**
+   * Serialized engine data payload for persistence (V2: canvas-scene/2 only).
+   */
+  export interface IMarkupEngineData {
+    format: 'canvas-scene/2';
+    version: string;
+    payload: string;
+  }
+
+  /**
+   * Engine type selector prop value.
+   */
+  export type TMarkupEngineType = 'canvas';
+
+  /**
+   * Markup engine interface for the canvas-scene/2 engine.
+   */
+  export interface IMarkupEngine {
+    initialize(): Promise<void>;
+    destroy(): void;
+    activateTool(tool: string): void;
+    deactivateTool(): void;
+    getActiveTool(): string | null;
+    addShape(shape: unknown): void;
+    removeShape(shape: unknown): void;
+    clearLayer(): void;
+    getShapes(): unknown[];
+    undo(): void;
+    redo(): void;
+    getData(): IMarkupEngineData;
+    loadData(data: IMarkupEngineData): void;
+    selectShape(shape: unknown): void;
+    getSelectedShape(): unknown | null;
+    onSelectionChange(cb: (shape: unknown | null) => void): () => void;
+    onShapeAdded(cb: (shape: unknown) => void): () => void;
+    onShapeModified(cb: (shape: unknown) => void): () => void;
+    onShapeRemoved(cb: (shape: unknown) => void): () => void;
+    readonly capabilities: IMarkupEngineCapabilities;
+  }
+
+  // ── Custom Geometry ────────────────────────────────────────────────────────
+
+  /**
+   * Options for SceneBuilderService.createModel().
+   */
+  export interface ISceneModelOptions {
+    /**
+     * When true, only addGeometry/addMaterial/addFragment can be used.
+     * When false (default), addMesh is also available.
+     */
+    conserveMemory?: boolean;
+    modelNameOverride?: string;
+  }
+
+  /**
+   * Builder API returned by SceneBuilderService.createModel().
+   * Use to add geometry, materials, and fragments to a custom model.
+   */
+  export interface IModelBuilderAPI {
+    addMaterial(name: string, material: unknown): void;
+    addGeometry(geometry: unknown): number;
+    addFragment(
+      geomIdOrGeom: number | unknown,
+      material: unknown | string,
+      transform: unknown,
+    ): number;
+    /** Only available when conserveMemory: false */
+    addMesh(mesh: unknown): boolean;
+  }
+
+  /**
+   * Manages viewer.overlays scenes for decoration and transient visuals.
+   *
+   * **Use for:** non-selectable decoration, transient highlights, helper visuals.
+   * **Do NOT use for:** objects requiring selection or dbId interaction.
+   * See SceneBuilderService for those use cases.
+   *
+   * @example
+   * ```typescript
+   * const overlay = new OverlayManager(viewer);
+   * overlay.createScene('highlights');
+   * const sphere = overlay.createSphere(0.5, 0xff0000);
+   * overlay.addMesh(sphere, 'highlights');
+   * ```
+   */
+  export class OverlayManager {
+    constructor(viewer: Autodesk.Viewing.GuiViewer3D);
+    createScene(name: string): void;
+    removeScene(name: string): void;
+    hasScene(name: string): boolean;
+    clearScene(name: string): void;
+    addMesh(mesh: unknown, sceneName: string): void;
+    removeMesh(mesh: unknown, sceneName: string): void;
+    createSphere(radius: number, color: number): unknown;
+    createBox(
+      width: number,
+      height: number,
+      depth: number,
+      color: number,
+    ): unknown;
+    createLine(from: unknown, to: unknown, color: number): unknown;
+    dispose(): void;
+  }
+
+  /**
+   * Creates model-like geometry using Autodesk.Viewing.SceneBuilder.
+   *
+   * **Use for:** objects that need selection, dbId, model aggregate events.
+   * **Do NOT use for:** simple decoration. Use OverlayManager instead.
+   * **Limitations:** no 2D models, no property database, no instance tree.
+   *
+   * @example
+   * ```typescript
+   * const svc = new SceneBuilderService(viewer);
+   * await svc.initialize();
+   * const builder = await svc.createModel();
+   * builder.addMaterial('red', material);
+   * const geomId = builder.addGeometry(geometry);
+   * builder.addFragment(geomId, 'red', transform);
+   * ```
+   */
+  export class SceneBuilderService {
+    constructor(viewer: Autodesk.Viewing.GuiViewer3D);
+    initialize(): Promise<void>;
+    createModel(options?: ISceneModelOptions): Promise<IModelBuilderAPI>;
+    removeModel(builder: IModelBuilderAPI): void;
+    isInitialized(): boolean;
+    destroy(): void;
+  }
+
+  // ── Property Database ──────────────────────────────────────────────────────
+
+  /**
+   * A single resolved property entry from the property database.
+   */
+  export interface IPropertyEntry {
+    name: string;
+    value: string | number | boolean;
+    category?: string;
+    dataType?: number;
+    units?: string;
+  }
+
+  /**
+   * Attribute definition from the property database.
+   */
+  export interface IAttributeDef {
+    id: number;
+    name: string;
+    category?: string;
+    dataType?: number;
+    units?: string;
+  }
+
+  /**
+   * Query the Autodesk Forge Viewer property database (runs in web worker).
+   *
+   * ⚠️ `executeQuery` functions run in a web worker. They must be self-contained:
+   * - No external variable references or imports
+   * - No `this` context
+   * - Return value must be JSON-serializable
+   *
+   * @example
+   * ```typescript
+   * const svc = new PropertyDatabaseService(viewer);
+   * const count = await svc.executeQuery(function(pdb) {
+   *   var n = 0;
+   *   pdb.enumObjects(function() { n++; });
+   *   return n;
+   * });
+   * ```
+   */
+  export class PropertyDatabaseService {
+    constructor(viewer: Autodesk.Viewing.GuiViewer3D);
+    /** Returns false for GLTF/GLB models which have no property database. */
+    isAvailable(): boolean;
+    executeQuery<T>(userFunction: (pdb: unknown) => T): Promise<T>;
+    getObjectProperties(dbId: number): Promise<IPropertyEntry[]>;
+    findObjectsByProperty(
+      propertyName: string,
+      value: string | number | boolean,
+    ): Promise<number[]>;
+    getAllAttributes(): Promise<IAttributeDef[]>;
+  }
+
+  // ── Selective Loading ──────────────────────────────────────────────────────
+
+  /**
+   * Axis-aligned bounding box spatial primitive for spatial queries.
+   */
+  export interface ISpatialPrimitive {
+    aabox: [
+      minX: number,
+      minY: number,
+      minZ: number,
+      maxX: number,
+      maxY: number,
+      maxZ: number,
+    ];
+  }
+
+  /**
+   * Spatial query for selective loading.
+   * Only applicable for SVF2 + loadDocumentNode() workflow.
+   */
+  export interface ISpatialQuery {
+    $intersects?: [ISpatialPrimitive];
+    $encloses?: [ISpatialPrimitive, unknown?, number?];
+    $extent?: [number];
+    $not?: ISpatialQuery;
+    $or?: ISpatialQuery[];
+    $and?: ISpatialQuery[];
+  }
+
+  /**
+   * Property-based query for selective loading.
+   * Keys use '?' prefix for property names.
+   * Example: `{ '?Base Constraint': "'Level 1'" }`
+   */
+  export interface IPropertyQuery {
+    $or?: IPropertyQuery[];
+    $and?: IPropertyQuery[];
+    $not?: IPropertyQuery;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Load filter for selective loading.
+   *
+   * ⚠️ Only applicable for SVF2 + loadDocumentNode() workflow (cloud-hosted URN models).
+   * Will throw UnsupportedCapabilityError for Local env (PDF/DWF direct file loading).
+   * Check `enhancedViewer.capabilities.selectiveLoading` before using.
+   */
+  export interface ILoadFilter {
+    spatial_query?: ISpatialQuery;
+    property_query?: IPropertyQuery;
+    root_condition?: 'and' | 'or';
+    /** 'exact' is default but slower; 'immediate' is faster but less precise */
+    spatial_behavior?: 'immediate' | 'exact';
+  }
+
+  // ── Viewer Preset Manager ─────────────────────────────────────────────────
+
+  /**
+   * Built-in viewer preset types.
+   * AEC = Architecture, Engineering, Construction settings.
+   * Navis = Navisworks-compatible settings.
+   */
+  export type TBuiltinPreset = 'AEC' | 'Navis';
+
+  /**
+   * Viewer settings preset configuration.
+   * Passed to ViewerPresetManager.applyPreset() or as `viewerPreset` prop.
+   */
+  export interface IViewerPresetSettings {
+    name?: string;
+    settings?: Record<string, boolean | number | string>;
+    extensions?: {
+      load?: string[];
+      unload?: string[];
+    };
+  }
+
+  /**
+   * Manages viewer behavior presets via Autodesk.Viewing.Profile / ProfileSettings.
+   *
+   * **Note:** This is NOT the Autodesk User Profile API. It controls viewer rendering
+   * and behavior settings (ambient shadows, ground reflection, etc.).
+   *
+   * @example
+   * ```typescript
+   * const pm = new ViewerPresetManager(viewer);
+   * pm.applyBuiltinPreset('AEC');
+   * pm.cloneAndApply('AEC', { settings: { ambientShadow: false } });
+   * ```
+   */
+  export class ViewerPresetManager {
+    constructor(viewer: Autodesk.Viewing.GuiViewer3D);
+    applyPreset(settings: IViewerPresetSettings): void;
+    applyBuiltinPreset(type: TBuiltinPreset): void;
+    cloneAndApply(
+      baseType: TBuiltinPreset,
+      overrides: Partial<IViewerPresetSettings>,
+    ): void;
+    registerFileTypePreset(
+      fileType: string,
+      settings: IViewerPresetSettings,
+    ): void;
+    resetToDefault(): void;
+    getCurrentPreset(): unknown;
+  }
+
+  // ── Capability Gating ──────────────────────────────────────────────────────
+
+  /**
+   * Capabilities advertised by the enhanced viewer object.
+   * Access via `enhancedViewer.capabilities`.
+   */
+  export interface IViewerCapabilities {
+    /** true only for SVF2 + loadDocumentNode workflow; false for Local PDF/DWF */
+    selectiveLoading: boolean;
+    /** true when enableSceneBuilder=true and extension loaded successfully */
+    sceneBuilder: boolean;
+    /** true when canvas markup engine is initialized */
+    canvas: boolean;
+    /** true when model has a property database (false for GLTF/GLB) */
+    propertyDatabase: boolean;
+  }
+
+  // ── Markups Panel ─────────────────────────────────────────────────────────
+
+  /** Single markup item displayed in the MarkupsPanel */
+  export interface IMarkupPanelItem {
+    /** Unique entity identifier */
+    id: string;
+    /**
+     * Markup kind — e.g. 'arrow' | 'rectangle' | 'ellipse' | 'polygon' |
+     * 'polyline' | 'line' | 'cloud' | 'polycloud' | 'text' | 'callout' |
+     * 'freehand' | 'highlighter' | 'image'
+     */
+    kind: string;
+    /** Optional label override; defaults to capitalised kind */
+    title?: string;
+    /** Display name of the creator */
+    authorName?: string;
+    /** Company / organisation of the creator */
+    authorCompany?: string;
+    /** Unix epoch milliseconds */
+    createdAt: number;
+    /** Whether the markup has been published/saved to the server */
+    isPublished?: boolean;
+    /** Override icon stroke colour (default: #ec4a41) */
+    color?: string;
+  }
+
+  // ── User Presence ─────────────────────────────────────────────────────────
+
+  /** Online user presence info for sidebar presence indicator */
+  export interface IUserPresence {
+    userId: string;
+    userName?: string;
+    color: string;
+    isActive: boolean;
+    lastSeen: number;
+    currentPageIndex?: number;
+    avatarUrl?: string;
+  }
+
+  // ── Collab Patch Types ────────────────────────────────────────────────────
+
+  export type TPatchOp = 'create' | 'update' | 'delete';
+
+  export interface ICanvasPatch {
+    op: TPatchOp;
+    shapeId: string;
+    /** Full shape data (omitted for delete) */
+    data?: unknown;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    actorId: string;
+    version: number;
+    nonce: number;
+    viewableGuid: string;
+    patchId?: string;
+  }
+
+  export interface ICanvasMarkupSceneV2 {
+    format: 'canvas-scene/2';
+    version: '2.0';
+    viewableGuid: string;
+    shapes: unknown[];
+    viewportBounds?: unknown;
+    createdAt: string;
+    updatedAt: string;
+  }
+
+  // ── Collab Adapter ────────────────────────────────────────────────────────
+
+  /** Identifies a collaboration room scoped to a single viewable page. */
+  export interface ICollabRoom {
+    viewableGuid: string;
+    roomId: string;
+  }
+
+  /**
+   * Result of `ICollabAdapter.fetchScene`.
+   * - `mode: 'full'`  — full scene replacement; call `api.loadScene(scene)`.
+   * - `mode: 'delta'` — incremental; call `api.applyPatches(deltaPatches)`.
+   */
+  export interface IFetchSceneResult {
+    mode: 'full' | 'delta';
+    scene: ICanvasMarkupSceneV2 | null;
+    deltaPatches?: ICanvasPatch[];
+  }
+
+  /** Transport-agnostic collab adapter — implement with Socket.IO, WebRTC, etc. */
+  export interface ICollabAdapter {
+    broadcastPatches(patches: ICanvasPatch[], room: ICollabRoom): Promise<void>;
+    fetchScene(room: ICollabRoom): Promise<IFetchSceneResult>;
+    onRemotePatches(room: ICollabRoom, cb: (patches: ICanvasPatch[]) => void): () => void;
+    joinRoom(room: ICollabRoom): void | Promise<void>;
+    leaveRoom(room: ICollabRoom): void | Promise<void>;
+    /** Optional: subscribe to server-initiated full-scene replacements (e.g. version restore). */
+    onRemoteSceneReplace?(room: ICollabRoom, cb: (scene: ICanvasMarkupSceneV2) => void): () => void;
+    /**
+     * Optional: drain the durable outbox for a room.
+     * Called after bootstrap to replay unACKed patches from a previous session.
+     */
+    drainOutboxForRoom?(room: ICollabRoom): Promise<ICanvasPatch[]>;
+    /** Optional: register a callback fired on transport reconnect for auto re-join. */
+    onReconnect?(cb: () => void): () => void;
+  }
+
+  export type TCollabStatus = 'idle' | 'joining' | 'connected' | 'disconnected' | 'error';
+
+  export interface ICollabStatusEvent {
+    status: TCollabStatus;
+    roomId?: string;
+    error?: Error;
+  }
+
+  // ── Updated ViewerForgePDF Props ──────────────────────────────────────────
+
+  /**
+   * Props for ViewerForgePDF component (v3.0.0)
+   */
+  export interface IViewerForgePDFProps {
+    /** URL/path to the document to load */
+    filePath: string;
+    /** File extension (pdf, dwf, dwfx, gltf, glb) */
+    fileExt: TSupportedFileExtension;
+    /** Toolbar visibility options */
+    toolbarOptions?: IToolbarOptions;
+    /** Callback to receive enhanced viewer instance when initialized */
+    setViewer?: (viewer: Autodesk.Viewing.GuiViewer3D | null) => void;
+    /** Enable custom markup toolbar (canvas engine). */
+    enableCustomMarkups?: boolean;
+    /** Configuration for DrawingManager. */
+    markupConfig?: IDrawingManagerConfig;
+    /**
+     * Markup engine — only `'canvas'` (canvas-scene/2) is supported.
+     * @default 'canvas' when enableCustomMarkups=true
+     */
+    markupEngine?: TMarkupEngineType;
+    /**
+     * Enable Autodesk.Viewing.SceneBuilder for model-like custom geometry.
+     * Exposes `enhancedViewer.sceneBuilder` when true.
+     * @default false
+     */
+    enableSceneBuilder?: boolean;
+    /**
+     * Load filter for selective loading.
+     * ⚠️ Only applicable for SVF2 + loadDocumentNode() workflow.
+     * Has no effect for Local env (PDF/DWF); check `capabilities.selectiveLoading`.
+     */
+    loadFilter?: ILoadFilter;
+    /** Apply a viewer behavior preset on initialization. */
+    viewerPreset?: IViewerPresetSettings;
+    /**
+     * Online users to display in the sidebar presence indicator.
+     * Pass from your collaboration layer (e.g. WebSocket/Supabase Presence).
+     * @default []
+     */
+    onlineUsers?: IUserPresence[];
+    /**
+     * Markup items to display in the Markups side panel.
+     * Build from your collaborative state (IMarkupElementCompact → IMarkupPanelItem).
+     * @default []
+     */
+    markupItems?: IMarkupPanelItem[];
+    /** Called when user clicks a markup row in the Markups panel. */
+    onMarkupItemClick?: (id: string) => void;
+    /**
+     * Called when a shape is selected or deselected on the canvas.
+     * Receives the shape `entityId` on selection, or `null` on deselect / toolbar close.
+     * Use this to look up per-shape metadata (author, timestamps) from your state store
+     * and pass it back via `selectedShapeInfo`.
+     */
+    onShapeSelect?: (entityId: string | null) => void;
+    /**
+     * Metadata to display in the Markup Edit Drawer history section for the
+     * currently selected shape. All fields are pre-formatted display strings so
+     * the library stays format-agnostic.
+     *
+     * When `historyEntries` is provided it takes priority over `createdBy`/`updatedBy`
+     * and renders the full timeline (newest-first, as ordered by the host app).
+     * @example
+     * selectedShapeInfo={{
+     *   historyEntries: [
+     *     'Edited by Bob on 31 Mar 2026, 01:28',
+     *     'Created by Alice on 17 Mar 2026, 09:40',
+     *   ],
+     * }}
+     * @example
+     * // Legacy fallback (still supported)
+     * selectedShapeInfo={{
+     *   createdBy: 'Created by Alice on 17 Mar 2026, 09:40',
+     *   updatedBy: 'Updated by Bob on 18 Mar 2026, 11:20',
+     * }}
+     */
+    selectedShapeInfo?: {
+      createdBy?: string;
+      updatedBy?: string;
+      /**
+       * Full history timeline for the selected shape, newest-first.
+       * Each entry is a pre-formatted string (e.g. 'Edited by Bob on 31 Mar 2026, 01:28').
+       * When present, supersedes `createdBy`/`updatedBy`.
+       */
+      historyEntries?: string[];
+    };
+    /**
+     * Enable canvas markup debug logger.
+     * Logs shape lifecycle, selection, property changes, history, and scene operations
+     * to the browser console. Exposes `window.__WH_MARKUP_DEBUG__` helpers at runtime.
+     * @default false
+     */
+    enableMarkupDebug?: boolean;
+    /** Load the Autodesk.BIM360.Minimap extension — shows a floating 2D minimap panel. Default: false */
+    enableMinimap?: boolean;
+    // ── Collaborative Markup ────────────────────────────────────────────────
+    /**
+     * Transport adapter for real-time collaborative markup.
+     * Implement `ICollabAdapter` using Socket.IO, WebRTC, or any transport.
+     * When provided (with `collabActorId` and `collabDrawingId`), the library
+     * creates a `CanvasCollabSessionService` internally and manages room lifecycle.
+     * If omitted, markup runs in offline mode.
+     */
+    collabAdapter?: ICollabAdapter;
+    /**
+     * Current user's actor ID for LWW conflict resolution and echo prevention.
+     * Required when `collabAdapter` is provided.
+     */
+    collabActorId?: string;
+    /**
+     * Drawing/document identifier used to construct room IDs.
+     * Room ID format: `${collabDrawingId}:${viewableGuid}`
+     * Required when `collabAdapter` is provided.
+     */
+    collabDrawingId?: string;
+    /**
+     * Canonical viewable GUID from the host app (e.g. from `/pages` endpoint).
+     * When provided, the library immediately joins the collab room for this page.
+     * Changes to this prop trigger a room re-join. If null/undefined, collab stays idle.
+     */
+    collabViewableGuid?: string | null;
+    /**
+     * Called when collaborative session status changes.
+     * @param evt - Status event with status, optional roomId, optional error
+     */
+    onCollabStatusChange?: (evt: ICollabStatusEvent) => void;
+    /**
+     * Called when a collaborative session error occurs.
+     */
+    onCollabError?: (error: Error) => void;
+
+    // ── Export with Markup ──────────────────────────────────────────────────
+    /**
+     * Optional override for the page list used during export.
+     *
+     * When provided, these GUIDs are passed to `fetchAllScenesForExport` instead of
+     * the Forge runtime GUIDs — eliminating the namespace mismatch that occurs when
+     * the BE persists scenes by canonical page UUIDs (different from Forge page GUIDs).
+     *
+     * Should return the same ordered page list you received from the `/pages` registration
+     * endpoint, mapped by `pageIndex`.
+     *
+     * @example
+     * ```tsx
+     * getExportViewablePages={() =>
+     *   pagesRef.current.map(p => ({ pageIndex: p.pageIndex, viewableGuid: p.viewableGUID }))
+     * }
+     * ```
+     */
+    getExportViewablePages?: () => Array<{ pageIndex: number; viewableGuid: string }>;
+
+    /**
+     * Async callback to fetch canvas-scene/2 data for ALL pages from the server
+     * before merging markup into the exported PDF.
+     *
+     * Input:  Array of every viewable GUID in the document.
+     * Output: Record mapping each GUID to its scene or `null` (no markup on that page).
+     *
+     * Rules enforced by the library:
+     * - Every GUID in the input must appear as a key in the output; missing keys throw.
+     * - Non-null scenes must have `format === 'canvas-scene/2'` and `viewableGuid` matching the key.
+     * - If all scenes are null/empty → original PDF is downloaded unchanged.
+     * - If this prop is omitted → "Export with Markup" is a no-op (logs a warning).
+     *
+     * @example
+     * ```tsx
+     * fetchAllScenesForExport={async (guids) => {
+     *   const res = await api.getMarkupScenes({ viewableGuids: guids });
+     *   // res: { [guid]: ICanvasMarkupSceneV2 | null }
+     *   return res;
+     * }}
+     * ```
+     */
+    fetchAllScenesForExport?: (
+      viewableGuids: string[],
+    ) => Promise<Record<string, ICanvasMarkupSceneV2 | null>>;
+
+    /**
+     * Called at key points in the export lifecycle.
+     * Use this to show loading spinners, progress indicators, and error toasts.
+     *
+     * @example
+     * ```tsx
+     * onExportStatus={(evt) => {
+     *   if (evt.status === 'start')   setExporting(true);
+     *   if (evt.status === 'success') setExporting(false);
+     *   if (evt.status === 'error')   { setExporting(false); toast.error(evt.error?.message); }
+     * }}
+     * ```
+     */
+    onExportStatus?: (event: IExportStatusEvent) => void;
+
+    /**
+     * Optional TTF font configuration for text export.
+     *
+     * Override when the default NotoSans TTF URLs are blocked by a CSP or network
+     * policy. Must point to valid `.ttf`/`.otf` files — WOFF2 causes invisible text
+     * in pdf-lib and should not be used.
+     *
+     * If omitted, the library fetches NotoSans TTF from Google Fonts CDN with an
+     * 8 s timeout, falling back to Helvetica (Latin-only) on failure.
+     *
+     * @example
+     * ```tsx
+     * <ViewerForgePDF
+     *   exportFontConfig={{
+     *     fontUrls: ['https://my-cdn.example.com/fonts/noto-sans.ttf'],
+     *     fetchTimeoutMs: 5000,
+     *   }}
+     * />
+     * ```
+     */
+    exportFontConfig?: IExportFontConfig;
+  }
+
+  /**
+   * Font configuration for PDF text export.
+   * Controls which TTF font file(s) are used when rendering text markups into PDF.
+   */
+  export interface IExportFontConfig {
+    /**
+     * Ordered list of TTF/OTF font URLs to try (primary first, then fallbacks).
+     * WOFF2 is not supported — only TTF/OTF files are accepted.
+     * @default NotoSans Regular from Google Fonts CDN
+     */
+    fontUrls?: string[];
+    /**
+     * Per-URL fetch timeout in milliseconds.
+     * @default 8000
+     */
+    fetchTimeoutMs?: number;
+  }
+
+  /**
+   * Export lifecycle event emitted by the canvas export pipeline.
+   */
+  export interface IExportStatusEvent {
+    /** Current stage of the export. */
+    status: 'start' | 'success' | 'error';
+    /** Present only when `status === 'error'`. */
+    error?: Error;
+  }
+
+  /**
+   * Canvas-scene/2 markup scene for a single page.
+   * Used as the element type in the `fetchAllScenesForExport` return value.
+   */
+  export interface ICanvasMarkupSceneV2 {
+    format: 'canvas-scene/2';
+    viewableGuid: string;
+    shapes: unknown[];
+    viewportBounds?: { x: number; y: number; width: number; height: number };
+    [key: string]: unknown;
+  }
 }