3dviewer-sdk 1.1.5 → 1.1.7

package/dist/index.d.mts

@@ -23,6 +23,7 @@ declare enum ViewerMessageType {
     WALK_THROUGH = "viewer-walk-through",
     ZOOM_WINDOW = "viewer-zoom-window",
     ZOOM_FIT = "viewer-zoom-fit",
+    DISPLAY_SET_BACKGROUND = "viewer-display-set-background",
     TOOLBAR_CONFIG = "viewer-toolbar-config",
     TOOLBAR_USE = "viewer-toolbar-use",
     PANEL_OPEN = "viewer-panel-open",
@@ -39,6 +40,8 @@ declare enum ViewerMessageType {
     STATES_OBJECTS_LIST = "viewer-states-objects-list",
     TREE_SELECT_NODE = "viewer-tree-select-node",
     TREE_SET_NODE_VISIBILITY = "viewer-tree-set-node-visibility",
+    NODE_SYNC_LOCKED_STATE = "viewer-node-sync-locked-state",
+    NODE_GET_LOCKED_STATE = "viewer-node-get-locked-state",
     TREE_GET_NODE_IDS = "viewer-tree-get-node-ids",
     TREE_NODE_IDS = "viewer-tree-node-ids",
     TREE_GET_NODES = "viewer-tree-get-nodes",
@@ -52,6 +55,8 @@ declare enum ViewerMessageType {
     PDF_CURRENT_PAGE = "viewer-pdf-current-page",
     HOME_CLICK = "viewer-home-click",
     NODE_SELECTION_CHANGE = "viewer-node-selection-change",
+    NODE_LOCKED_STATE = "viewer-node-locked-state",
+    NODE_LOCKED_STATE_CHANGE = "viewer-node-locked-state-change",
     PAN_CHANGE = "viewer-pan-change"
 }
 type LanguageCode = "en" | "vn";
@@ -59,6 +64,19 @@ type NodeSelectionChangePayload = {
     nodeIds: string[];
     timestamp: number;
 };
+type ViewerRgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+type ViewerRgbaColor = ViewerRgbColor & {
+    a: number;
+};
+type ViewerBackgroundColorInput = ViewerRgbColor | ViewerRgbaColor | string;
+type ViewerBackgroundPayload = {
+    top: ViewerRgbColor;
+    bottom?: ViewerRgbColor;
+};
 type CameraZoomPayload = {
     requestId?: string;
     percent: number;
@@ -130,6 +148,21 @@ type StateObjectItem = {
         type: string;
     };
 };
+type SyncLockedStatePayload = {
+    persistentIds?: string[];
+    treeNodeIds?: string[];
+    requestId?: string;
+};
+type GetLockedStatePayload = {
+    requestId?: string;
+};
+type LockedStatePayload = {
+    requestId?: string;
+    persistentIds: string[];
+    treeNodeIds: string[];
+    renderedNodeIds: string[];
+    timestamp: number;
+};
 type TreeNodeItem = {
     id: string;
     name: string;
@@ -164,6 +197,8 @@ type ViewerEventMap = {
     };
     "camera:zoom": CameraZoomPayload;
     "node:selection-change": NodeSelectionChangePayload;
+    "node:locked-state": LockedStatePayload;
+    "node:locked-state-change": LockedStatePayload;
     "interaction:pan-change": {
         enabled: boolean;
     };
@@ -289,6 +324,22 @@ declare class CameraModule {
     private postCameraGetZoom;
 }
 
+type BackgroundOptionsInput = {
+    top: ViewerBackgroundColorInput;
+    bottom?: ViewerBackgroundColorInput;
+};
+type InitialBackground = ViewerBackgroundColorInput | BackgroundOptionsInput;
+
+type SetBackgroundOptions = BackgroundOptionsInput;
+declare class DisplayModule {
+    private viewer;
+    constructor(viewer: Viewer3D);
+    setBackgroundColor(color: ViewerBackgroundColorInput): void;
+    setBackgroundGradient(top: ViewerBackgroundColorInput, bottom: ViewerBackgroundColorInput): void;
+    setBackground(options: SetBackgroundOptions): void;
+    private postBackground;
+}
+
 declare class InteractionModule {
     private viewer;
     on: {
@@ -316,6 +367,11 @@ declare class InteractionModule {
     private setDrawMode;
 }
 
+type LockedState = LockedStatePayload;
+type SyncLockedStateInput = Omit<SyncLockedStatePayload, "requestId">;
+type LockedStateRequestOptions = {
+    timeoutMs?: number;
+};
 declare class NodeModule {
     private viewer;
     on: {
@@ -323,8 +379,11 @@ declare class NodeModule {
             nodeIds: string[];
             timestamp: number;
         }) => void) => () => void;
+        lockedStateChange: (cb: (payload: LockedState) => void) => () => void;
     };
     constructor(viewer: Viewer3D);
+    syncLockedState(input: SyncLockedStateInput, options?: LockedStateRequestOptions): Promise<LockedState>;
+    getLockedState(options?: LockedStateRequestOptions): Promise<LockedState>;
 }
 
 type FilesConfig = {
@@ -647,6 +706,7 @@ type Viewer3DOptions = {
     uploadPath?: string;
     file?: File;
     initialToolbar?: InitialToolbarUse;
+    initialBackground?: InitialBackground;
     ui?: {
         loadingIndicator?: boolean;
     };
@@ -666,6 +726,7 @@ declare class Viewer3D {
     private loadingState;
     private emitter;
     camera: CameraModule;
+    display: DisplayModule;
     interaction: InteractionModule;
     node: NodeModule;
     files: FilesModule;
@@ -691,6 +752,7 @@ declare class Viewer3D {
     private ensureInit;
     private withInitialOptions;
     private normalizeInitialToolbar;
+    private normalizeInitialBackground;
     _on<K extends SdkEventKey>(event: K, cb: (payload: SdkEventPayload<K>) => void): () => void;
     _off<K extends SdkEventKey>(event: K, cb: (payload: SdkEventPayload<K>) => void): void;
     _emit<K extends SdkEventKey>(event: K, payload: SdkEventPayload<K>): void;
@@ -702,4 +764,4 @@ declare class Viewer3D {
     private handleMessage;
 }
 
-export { type CameraZoomPayload, type ConvertOptions, type ConvertV2Options, type CreatePipelineOptions, type FileInfoCheckInput, type FileInfoCheckPayloadItem, type FilesConfig, type InitialToolbarUse, type LanguageCode, type LoadStage, type LoadStatePayload, type MarkupAction, type MarkupListItem, type MarkupOperationResultPayload, type ObjectPropertiesGetOptions, type ObjectPropertiesResult, type PreparedViewerData, Viewer3D, type Viewer3DOptions, type ViewerLoadingChangePayload, type ViewerLoadingPhase, type ViewerReadyPayload };
+export { type CameraZoomPayload, type ConvertOptions, type ConvertV2Options, type CreatePipelineOptions, type FileInfoCheckInput, type FileInfoCheckPayloadItem, type FilesConfig, type GetLockedStatePayload, type InitialBackground, type InitialToolbarUse, type LanguageCode, type LoadStage, type LoadStatePayload, type LockedState, type LockedStatePayload, type LockedStateRequestOptions, type MarkupAction, type MarkupListItem, type MarkupOperationResultPayload, type ObjectPropertiesGetOptions, type ObjectPropertiesResult, type PreparedViewerData, type SetBackgroundOptions, type SyncLockedStateInput, type SyncLockedStatePayload, Viewer3D, type Viewer3DOptions, type ViewerBackgroundColorInput, type ViewerBackgroundPayload, type ViewerLoadingChangePayload, type ViewerLoadingPhase, type ViewerReadyPayload, type ViewerRgbColor, type ViewerRgbaColor };

package/dist/index.d.ts

@@ -23,6 +23,7 @@ declare enum ViewerMessageType {
     WALK_THROUGH = "viewer-walk-through",
     ZOOM_WINDOW = "viewer-zoom-window",
     ZOOM_FIT = "viewer-zoom-fit",
+    DISPLAY_SET_BACKGROUND = "viewer-display-set-background",
     TOOLBAR_CONFIG = "viewer-toolbar-config",
     TOOLBAR_USE = "viewer-toolbar-use",
     PANEL_OPEN = "viewer-panel-open",
@@ -39,6 +40,8 @@ declare enum ViewerMessageType {
     STATES_OBJECTS_LIST = "viewer-states-objects-list",
     TREE_SELECT_NODE = "viewer-tree-select-node",
     TREE_SET_NODE_VISIBILITY = "viewer-tree-set-node-visibility",
+    NODE_SYNC_LOCKED_STATE = "viewer-node-sync-locked-state",
+    NODE_GET_LOCKED_STATE = "viewer-node-get-locked-state",
     TREE_GET_NODE_IDS = "viewer-tree-get-node-ids",
     TREE_NODE_IDS = "viewer-tree-node-ids",
     TREE_GET_NODES = "viewer-tree-get-nodes",
@@ -52,6 +55,8 @@ declare enum ViewerMessageType {
     PDF_CURRENT_PAGE = "viewer-pdf-current-page",
     HOME_CLICK = "viewer-home-click",
     NODE_SELECTION_CHANGE = "viewer-node-selection-change",
+    NODE_LOCKED_STATE = "viewer-node-locked-state",
+    NODE_LOCKED_STATE_CHANGE = "viewer-node-locked-state-change",
     PAN_CHANGE = "viewer-pan-change"
 }
 type LanguageCode = "en" | "vn";
@@ -59,6 +64,19 @@ type NodeSelectionChangePayload = {
     nodeIds: string[];
     timestamp: number;
 };
+type ViewerRgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+type ViewerRgbaColor = ViewerRgbColor & {
+    a: number;
+};
+type ViewerBackgroundColorInput = ViewerRgbColor | ViewerRgbaColor | string;
+type ViewerBackgroundPayload = {
+    top: ViewerRgbColor;
+    bottom?: ViewerRgbColor;
+};
 type CameraZoomPayload = {
     requestId?: string;
     percent: number;
@@ -130,6 +148,21 @@ type StateObjectItem = {
         type: string;
     };
 };
+type SyncLockedStatePayload = {
+    persistentIds?: string[];
+    treeNodeIds?: string[];
+    requestId?: string;
+};
+type GetLockedStatePayload = {
+    requestId?: string;
+};
+type LockedStatePayload = {
+    requestId?: string;
+    persistentIds: string[];
+    treeNodeIds: string[];
+    renderedNodeIds: string[];
+    timestamp: number;
+};
 type TreeNodeItem = {
     id: string;
     name: string;
@@ -164,6 +197,8 @@ type ViewerEventMap = {
     };
     "camera:zoom": CameraZoomPayload;
     "node:selection-change": NodeSelectionChangePayload;
+    "node:locked-state": LockedStatePayload;
+    "node:locked-state-change": LockedStatePayload;
     "interaction:pan-change": {
         enabled: boolean;
     };
@@ -289,6 +324,22 @@ declare class CameraModule {
     private postCameraGetZoom;
 }
 
+type BackgroundOptionsInput = {
+    top: ViewerBackgroundColorInput;
+    bottom?: ViewerBackgroundColorInput;
+};
+type InitialBackground = ViewerBackgroundColorInput | BackgroundOptionsInput;
+
+type SetBackgroundOptions = BackgroundOptionsInput;
+declare class DisplayModule {
+    private viewer;
+    constructor(viewer: Viewer3D);
+    setBackgroundColor(color: ViewerBackgroundColorInput): void;
+    setBackgroundGradient(top: ViewerBackgroundColorInput, bottom: ViewerBackgroundColorInput): void;
+    setBackground(options: SetBackgroundOptions): void;
+    private postBackground;
+}
+
 declare class InteractionModule {
     private viewer;
     on: {
@@ -316,6 +367,11 @@ declare class InteractionModule {
     private setDrawMode;
 }
 
+type LockedState = LockedStatePayload;
+type SyncLockedStateInput = Omit<SyncLockedStatePayload, "requestId">;
+type LockedStateRequestOptions = {
+    timeoutMs?: number;
+};
 declare class NodeModule {
     private viewer;
     on: {
@@ -323,8 +379,11 @@ declare class NodeModule {
             nodeIds: string[];
             timestamp: number;
         }) => void) => () => void;
+        lockedStateChange: (cb: (payload: LockedState) => void) => () => void;
     };
     constructor(viewer: Viewer3D);
+    syncLockedState(input: SyncLockedStateInput, options?: LockedStateRequestOptions): Promise<LockedState>;
+    getLockedState(options?: LockedStateRequestOptions): Promise<LockedState>;
 }
 
 type FilesConfig = {
@@ -647,6 +706,7 @@ type Viewer3DOptions = {
     uploadPath?: string;
     file?: File;
     initialToolbar?: InitialToolbarUse;
+    initialBackground?: InitialBackground;
     ui?: {
         loadingIndicator?: boolean;
     };
@@ -666,6 +726,7 @@ declare class Viewer3D {
     private loadingState;
     private emitter;
     camera: CameraModule;
+    display: DisplayModule;
     interaction: InteractionModule;
     node: NodeModule;
     files: FilesModule;
@@ -691,6 +752,7 @@ declare class Viewer3D {
     private ensureInit;
     private withInitialOptions;
     private normalizeInitialToolbar;
+    private normalizeInitialBackground;
     _on<K extends SdkEventKey>(event: K, cb: (payload: SdkEventPayload<K>) => void): () => void;
     _off<K extends SdkEventKey>(event: K, cb: (payload: SdkEventPayload<K>) => void): void;
     _emit<K extends SdkEventKey>(event: K, payload: SdkEventPayload<K>): void;
@@ -702,4 +764,4 @@ declare class Viewer3D {
     private handleMessage;
 }
 
-export { type CameraZoomPayload, type ConvertOptions, type ConvertV2Options, type CreatePipelineOptions, type FileInfoCheckInput, type FileInfoCheckPayloadItem, type FilesConfig, type InitialToolbarUse, type LanguageCode, type LoadStage, type LoadStatePayload, type MarkupAction, type MarkupListItem, type MarkupOperationResultPayload, type ObjectPropertiesGetOptions, type ObjectPropertiesResult, type PreparedViewerData, Viewer3D, type Viewer3DOptions, type ViewerLoadingChangePayload, type ViewerLoadingPhase, type ViewerReadyPayload };
+export { type CameraZoomPayload, type ConvertOptions, type ConvertV2Options, type CreatePipelineOptions, type FileInfoCheckInput, type FileInfoCheckPayloadItem, type FilesConfig, type GetLockedStatePayload, type InitialBackground, type InitialToolbarUse, type LanguageCode, type LoadStage, type LoadStatePayload, type LockedState, type LockedStatePayload, type LockedStateRequestOptions, type MarkupAction, type MarkupListItem, type MarkupOperationResultPayload, type ObjectPropertiesGetOptions, type ObjectPropertiesResult, type PreparedViewerData, type SetBackgroundOptions, type SyncLockedStateInput, type SyncLockedStatePayload, Viewer3D, type Viewer3DOptions, type ViewerBackgroundColorInput, type ViewerBackgroundPayload, type ViewerLoadingChangePayload, type ViewerLoadingPhase, type ViewerReadyPayload, type ViewerRgbColor, type ViewerRgbaColor };

package/dist/index.js

@@ -99,6 +99,105 @@ var CameraModule = class {
   }
 };
 
+// src/modules/display.shared.ts
+function isBackgroundOptionsInput(value) {
+  return typeof value === "object" && value !== null && "top" in value;
+}
+function clampColorChannel(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(255, Math.max(0, Math.round(value)));
+}
+function normalizeHexColor(color) {
+  const normalized = color.trim();
+  const match = normalized.match(/^#?([a-f\d]{3}|[a-f\d]{6})$/i);
+  if (!match) {
+    throw new Error(
+      `Invalid background color "${color}". Use #RGB, #RRGGBB, rgb(...), rgba(...), or { r, g, b }.`
+    );
+  }
+  const hex = match[1].length === 3 ? match[1].split("").map((char) => `${char}${char}`).join("") : match[1];
+  return {
+    r: Number.parseInt(hex.slice(0, 2), 16),
+    g: Number.parseInt(hex.slice(2, 4), 16),
+    b: Number.parseInt(hex.slice(4, 6), 16)
+  };
+}
+function normalizeFunctionalRgbColor(color) {
+  const normalized = color.trim();
+  const match = normalized.match(/^rgba?\(\s*([^)]+)\s*\)$/i);
+  if (!match) return null;
+  const values = match[1].split(",").map((value) => value.trim()).filter((value) => value !== "");
+  if (values.length !== 3 && values.length !== 4) {
+    throw new Error(
+      `Invalid background color "${color}". rgb()/rgba() requires 3 RGB channels and optional alpha.`
+    );
+  }
+  const [r, g, b] = values;
+  return {
+    r: clampColorChannel(Number(r)),
+    g: clampColorChannel(Number(g)),
+    b: clampColorChannel(Number(b))
+  };
+}
+function normalizeBackgroundColor(color) {
+  var _a;
+  if (typeof color === "string") {
+    return (_a = normalizeFunctionalRgbColor(color)) != null ? _a : normalizeHexColor(color);
+  }
+  return {
+    r: clampColorChannel(color.r),
+    g: clampColorChannel(color.g),
+    b: clampColorChannel(color.b)
+  };
+}
+function normalizeBackgroundOptions(options) {
+  return {
+    top: normalizeBackgroundColor(options.top),
+    bottom: options.bottom === void 0 ? void 0 : normalizeBackgroundColor(options.bottom)
+  };
+}
+function normalizeInitialBackground(background) {
+  if (isBackgroundOptionsInput(background)) {
+    return normalizeBackgroundOptions(background);
+  }
+  const solidColor = normalizeBackgroundColor(
+    background
+  );
+  return {
+    top: solidColor,
+    bottom: solidColor
+  };
+}
+
+// src/modules/display.module.ts
+var DisplayModule = class {
+  constructor(viewer) {
+    this.viewer = viewer;
+  }
+  setBackgroundColor(color) {
+    const normalizedColor = normalizeBackgroundColor(color);
+    this.postBackground({
+      top: normalizedColor,
+      bottom: normalizedColor
+    });
+  }
+  setBackgroundGradient(top, bottom) {
+    this.postBackground({
+      top: normalizeBackgroundColor(top),
+      bottom: normalizeBackgroundColor(bottom)
+    });
+  }
+  setBackground(options) {
+    this.postBackground(normalizeBackgroundOptions(options));
+  }
+  postBackground(payload) {
+    this.viewer.postToViewer(
+      "viewer-display-set-background" /* DISPLAY_SET_BACKGROUND */,
+      payload
+    );
+  }
+};
+
 // src/modules/interaction.module.ts
 var InteractionModule = class {
   constructor(viewer) {
@@ -161,14 +260,74 @@ var InteractionModule = class {
 };
 
 // src/modules/node.module.ts
+function createRequestId2(prefix) {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function normalizeIds(values) {
+  if (!values) return void 0;
+  const normalized = Array.from(
+    new Set(
+      values.map((value) => String(value).trim()).filter((value) => value !== "")
+    )
+  );
+  return normalized.length > 0 ? normalized : void 0;
+}
 var NodeModule = class {
   constructor(viewer) {
     this.viewer = viewer;
     this.on = {
       // SDK no longer supports first-node-only select events; listen to selectionChange for the full node list.
-      selectionChange: (cb) => this.viewer._on("node:selection-change", cb)
+      selectionChange: (cb) => this.viewer._on("node:selection-change", cb),
+      lockedStateChange: (cb) => this.viewer._on("node:locked-state-change", cb)
     };
   }
+  syncLockedState(input, options) {
+    var _a;
+    const requestId = createRequestId2("locked_state_sync");
+    const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new Error("Timeout while syncing locked state with viewer"));
+      }, timeoutMs);
+      const off = this.viewer._on("node:locked-state", (payload2) => {
+        if (payload2.requestId !== requestId) return;
+        clearTimeout(timer);
+        off();
+        resolve(payload2);
+      });
+      const payload = {
+        requestId,
+        persistentIds: normalizeIds(input.persistentIds),
+        treeNodeIds: normalizeIds(input.treeNodeIds)
+      };
+      this.viewer.postToViewer(
+        "viewer-node-sync-locked-state" /* NODE_SYNC_LOCKED_STATE */,
+        payload
+      );
+    });
+  }
+  getLockedState(options) {
+    var _a;
+    const requestId = createRequestId2("locked_state_get");
+    const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new Error("Timeout while getting locked state from viewer"));
+      }, timeoutMs);
+      const off = this.viewer._on("node:locked-state", (payload) => {
+        if (payload.requestId !== requestId) return;
+        clearTimeout(timer);
+        off();
+        resolve(payload);
+      });
+      this.viewer.postToViewer(
+        "viewer-node-get-locked-state" /* NODE_GET_LOCKED_STATE */,
+        { requestId }
+      );
+    });
+  }
 };
 
 // src/modules/files.module.ts
@@ -734,7 +893,7 @@ var FilesModule = class {
 };
 
 // src/modules/toolbar.module.ts
-function createRequestId2(prefix) {
+function createRequestId3(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 var ALL_3D_TOOLBAR_OPERATORS = [
@@ -892,7 +1051,7 @@ var ToolbarModule = class {
   }
   getSheets(options) {
     var _a;
-    const requestId = createRequestId2("sheets");
+    const requestId = createRequestId3("sheets");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -910,7 +1069,7 @@ var ToolbarModule = class {
   }
   getObjectProperties(options) {
     var _a;
-    const requestId = createRequestId2("object_properties");
+    const requestId = createRequestId3("object_properties");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       var _a2;
@@ -932,7 +1091,7 @@ var ToolbarModule = class {
   }
   getLinkedObjects(options) {
     var _a;
-    const requestId = createRequestId2("linked_objects");
+    const requestId = createRequestId3("linked_objects");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -950,7 +1109,7 @@ var ToolbarModule = class {
   }
   getStatesObjects(options) {
     var _a;
-    const requestId = createRequestId2("states_objects");
+    const requestId = createRequestId3("states_objects");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1038,7 +1197,7 @@ var ToolbarModule = class {
 };
 
 // src/modules/model-tree.module.ts
-function createRequestId3(prefix) {
+function createRequestId4(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 function buildTree(nodes, rootNodeIds) {
@@ -1112,7 +1271,7 @@ var ModelTreeModule = class {
     this.setNodeVisibility(nodeIds, true);
   }
   getNodeIds(options) {
-    const requestId = createRequestId3("tree");
+    const requestId = createRequestId4("tree");
     const timeoutMs = this.resolveTimeoutMs(options);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1138,7 +1297,7 @@ var ModelTreeModule = class {
     return this.requestNodes(options).then((response) => buildTree(response.nodes, response.rootNodeIds));
   }
   requestNodes(options) {
-    const requestId = createRequestId3("tree_nodes");
+    const requestId = createRequestId4("tree_nodes");
     const timeoutMs = this.resolveTimeoutMs(options);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1190,7 +1349,7 @@ var ModelTreeModule = class {
 };
 
 // src/modules/markup.module.ts
-function createRequestId4(prefix) {
+function createRequestId5(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 var MarkupModule = class {
@@ -1244,7 +1403,7 @@ var MarkupModule = class {
   }
   getList(options) {
     var _a;
-    const requestId = createRequestId4("markup-list");
+    const requestId = createRequestId5("markup-list");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1262,7 +1421,7 @@ var MarkupModule = class {
   }
   runRequest(prefix, messageType, eventName, options) {
     var _a;
-    const requestId = createRequestId4(prefix);
+    const requestId = createRequestId5(prefix);
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1308,7 +1467,7 @@ function createObjectPropertiesError(message, errorStatus) {
   error.errorStatus = errorStatus;
   return error;
 }
-function createRequestId5(prefix) {
+function createRequestId6(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 function normalizeNodeIds(nodeIds) {
@@ -1326,7 +1485,7 @@ var ObjectPropertiesModule = class {
   getByNodeIds(nodeIds, options) {
     var _a;
     const normalizedNodeIds = normalizeNodeIds(nodeIds);
-    const requestId = createRequestId5("object_properties");
+    const requestId = createRequestId6("object_properties");
     if (normalizedNodeIds.length === 0) {
       return Promise.resolve({
         requestId,
@@ -1439,6 +1598,30 @@ var Viewer3D = class {
           });
           break;
         }
+        case "viewer-node-locked-state" /* NODE_LOCKED_STATE */: {
+          const payload = data.payload;
+          if (!payload) break;
+          this._emit("node:locked-state", {
+            requestId: payload.requestId ? String(payload.requestId) : void 0,
+            persistentIds: Array.isArray(payload.persistentIds) ? payload.persistentIds.map(String) : [],
+            treeNodeIds: Array.isArray(payload.treeNodeIds) ? payload.treeNodeIds.map(String) : [],
+            renderedNodeIds: Array.isArray(payload.renderedNodeIds) ? payload.renderedNodeIds.map(String) : [],
+            timestamp: Number(payload.timestamp) || Date.now()
+          });
+          break;
+        }
+        case "viewer-node-locked-state-change" /* NODE_LOCKED_STATE_CHANGE */: {
+          const payload = data.payload;
+          if (!payload) break;
+          this._emit("node:locked-state-change", {
+            requestId: payload.requestId ? String(payload.requestId) : void 0,
+            persistentIds: Array.isArray(payload.persistentIds) ? payload.persistentIds.map(String) : [],
+            treeNodeIds: Array.isArray(payload.treeNodeIds) ? payload.treeNodeIds.map(String) : [],
+            renderedNodeIds: Array.isArray(payload.renderedNodeIds) ? payload.renderedNodeIds.map(String) : [],
+            timestamp: Number(payload.timestamp) || Date.now()
+          });
+          break;
+        }
         case "viewer-pan-change" /* PAN_CHANGE */:
           this._emit("interaction:pan-change", {
             enabled: Boolean((_a = data.payload) == null ? void 0 : _a.enabled)
@@ -1662,6 +1845,7 @@ var Viewer3D = class {
       }
     };
     this.camera = new CameraModule(this);
+    this.display = new DisplayModule(this);
     this.interaction = new InteractionModule(this);
     this.node = new NodeModule(this);
     this.files = new FilesModule(this);
@@ -1789,6 +1973,13 @@ var Viewer3D = class {
       if (((_a = this.options.ui) == null ? void 0 : _a.loadingIndicator) === false) {
         parsedUrl.searchParams.set("loadingIndicator", "false");
       }
+      const initialBackground = this.normalizeInitialBackground();
+      if (initialBackground) {
+        parsedUrl.searchParams.set(
+          "initialBackground",
+          JSON.stringify(initialBackground)
+        );
+      }
       return parsedUrl.toString();
     } catch {
       return url;
@@ -1821,6 +2012,11 @@ var Viewer3D = class {
       {}
     );
   }
+  normalizeInitialBackground() {
+    const initialBackground = this.options.initialBackground;
+    if (!initialBackground) return null;
+    return normalizeInitialBackground(initialBackground);
+  }
   // ===== typed internal events used by modules =====
   _on(event, cb) {
     return this.emitter.on(event, cb);

package/dist/index.mjs

@@ -73,6 +73,105 @@ var CameraModule = class {
   }
 };
 
+// src/modules/display.shared.ts
+function isBackgroundOptionsInput(value) {
+  return typeof value === "object" && value !== null && "top" in value;
+}
+function clampColorChannel(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(255, Math.max(0, Math.round(value)));
+}
+function normalizeHexColor(color) {
+  const normalized = color.trim();
+  const match = normalized.match(/^#?([a-f\d]{3}|[a-f\d]{6})$/i);
+  if (!match) {
+    throw new Error(
+      `Invalid background color "${color}". Use #RGB, #RRGGBB, rgb(...), rgba(...), or { r, g, b }.`
+    );
+  }
+  const hex = match[1].length === 3 ? match[1].split("").map((char) => `${char}${char}`).join("") : match[1];
+  return {
+    r: Number.parseInt(hex.slice(0, 2), 16),
+    g: Number.parseInt(hex.slice(2, 4), 16),
+    b: Number.parseInt(hex.slice(4, 6), 16)
+  };
+}
+function normalizeFunctionalRgbColor(color) {
+  const normalized = color.trim();
+  const match = normalized.match(/^rgba?\(\s*([^)]+)\s*\)$/i);
+  if (!match) return null;
+  const values = match[1].split(",").map((value) => value.trim()).filter((value) => value !== "");
+  if (values.length !== 3 && values.length !== 4) {
+    throw new Error(
+      `Invalid background color "${color}". rgb()/rgba() requires 3 RGB channels and optional alpha.`
+    );
+  }
+  const [r, g, b] = values;
+  return {
+    r: clampColorChannel(Number(r)),
+    g: clampColorChannel(Number(g)),
+    b: clampColorChannel(Number(b))
+  };
+}
+function normalizeBackgroundColor(color) {
+  var _a;
+  if (typeof color === "string") {
+    return (_a = normalizeFunctionalRgbColor(color)) != null ? _a : normalizeHexColor(color);
+  }
+  return {
+    r: clampColorChannel(color.r),
+    g: clampColorChannel(color.g),
+    b: clampColorChannel(color.b)
+  };
+}
+function normalizeBackgroundOptions(options) {
+  return {
+    top: normalizeBackgroundColor(options.top),
+    bottom: options.bottom === void 0 ? void 0 : normalizeBackgroundColor(options.bottom)
+  };
+}
+function normalizeInitialBackground(background) {
+  if (isBackgroundOptionsInput(background)) {
+    return normalizeBackgroundOptions(background);
+  }
+  const solidColor = normalizeBackgroundColor(
+    background
+  );
+  return {
+    top: solidColor,
+    bottom: solidColor
+  };
+}
+
+// src/modules/display.module.ts
+var DisplayModule = class {
+  constructor(viewer) {
+    this.viewer = viewer;
+  }
+  setBackgroundColor(color) {
+    const normalizedColor = normalizeBackgroundColor(color);
+    this.postBackground({
+      top: normalizedColor,
+      bottom: normalizedColor
+    });
+  }
+  setBackgroundGradient(top, bottom) {
+    this.postBackground({
+      top: normalizeBackgroundColor(top),
+      bottom: normalizeBackgroundColor(bottom)
+    });
+  }
+  setBackground(options) {
+    this.postBackground(normalizeBackgroundOptions(options));
+  }
+  postBackground(payload) {
+    this.viewer.postToViewer(
+      "viewer-display-set-background" /* DISPLAY_SET_BACKGROUND */,
+      payload
+    );
+  }
+};
+
 // src/modules/interaction.module.ts
 var InteractionModule = class {
   constructor(viewer) {
@@ -135,14 +234,74 @@ var InteractionModule = class {
 };
 
 // src/modules/node.module.ts
+function createRequestId2(prefix) {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function normalizeIds(values) {
+  if (!values) return void 0;
+  const normalized = Array.from(
+    new Set(
+      values.map((value) => String(value).trim()).filter((value) => value !== "")
+    )
+  );
+  return normalized.length > 0 ? normalized : void 0;
+}
 var NodeModule = class {
   constructor(viewer) {
     this.viewer = viewer;
     this.on = {
       // SDK no longer supports first-node-only select events; listen to selectionChange for the full node list.
-      selectionChange: (cb) => this.viewer._on("node:selection-change", cb)
+      selectionChange: (cb) => this.viewer._on("node:selection-change", cb),
+      lockedStateChange: (cb) => this.viewer._on("node:locked-state-change", cb)
     };
   }
+  syncLockedState(input, options) {
+    var _a;
+    const requestId = createRequestId2("locked_state_sync");
+    const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new Error("Timeout while syncing locked state with viewer"));
+      }, timeoutMs);
+      const off = this.viewer._on("node:locked-state", (payload2) => {
+        if (payload2.requestId !== requestId) return;
+        clearTimeout(timer);
+        off();
+        resolve(payload2);
+      });
+      const payload = {
+        requestId,
+        persistentIds: normalizeIds(input.persistentIds),
+        treeNodeIds: normalizeIds(input.treeNodeIds)
+      };
+      this.viewer.postToViewer(
+        "viewer-node-sync-locked-state" /* NODE_SYNC_LOCKED_STATE */,
+        payload
+      );
+    });
+  }
+  getLockedState(options) {
+    var _a;
+    const requestId = createRequestId2("locked_state_get");
+    const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new Error("Timeout while getting locked state from viewer"));
+      }, timeoutMs);
+      const off = this.viewer._on("node:locked-state", (payload) => {
+        if (payload.requestId !== requestId) return;
+        clearTimeout(timer);
+        off();
+        resolve(payload);
+      });
+      this.viewer.postToViewer(
+        "viewer-node-get-locked-state" /* NODE_GET_LOCKED_STATE */,
+        { requestId }
+      );
+    });
+  }
 };
 
 // src/modules/files.module.ts
@@ -708,7 +867,7 @@ var FilesModule = class {
 };
 
 // src/modules/toolbar.module.ts
-function createRequestId2(prefix) {
+function createRequestId3(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 var ALL_3D_TOOLBAR_OPERATORS = [
@@ -866,7 +1025,7 @@ var ToolbarModule = class {
   }
   getSheets(options) {
     var _a;
-    const requestId = createRequestId2("sheets");
+    const requestId = createRequestId3("sheets");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -884,7 +1043,7 @@ var ToolbarModule = class {
   }
   getObjectProperties(options) {
     var _a;
-    const requestId = createRequestId2("object_properties");
+    const requestId = createRequestId3("object_properties");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       var _a2;
@@ -906,7 +1065,7 @@ var ToolbarModule = class {
   }
   getLinkedObjects(options) {
     var _a;
-    const requestId = createRequestId2("linked_objects");
+    const requestId = createRequestId3("linked_objects");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -924,7 +1083,7 @@ var ToolbarModule = class {
   }
   getStatesObjects(options) {
     var _a;
-    const requestId = createRequestId2("states_objects");
+    const requestId = createRequestId3("states_objects");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1012,7 +1171,7 @@ var ToolbarModule = class {
 };
 
 // src/modules/model-tree.module.ts
-function createRequestId3(prefix) {
+function createRequestId4(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 function buildTree(nodes, rootNodeIds) {
@@ -1086,7 +1245,7 @@ var ModelTreeModule = class {
     this.setNodeVisibility(nodeIds, true);
   }
   getNodeIds(options) {
-    const requestId = createRequestId3("tree");
+    const requestId = createRequestId4("tree");
     const timeoutMs = this.resolveTimeoutMs(options);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1112,7 +1271,7 @@ var ModelTreeModule = class {
     return this.requestNodes(options).then((response) => buildTree(response.nodes, response.rootNodeIds));
   }
   requestNodes(options) {
-    const requestId = createRequestId3("tree_nodes");
+    const requestId = createRequestId4("tree_nodes");
     const timeoutMs = this.resolveTimeoutMs(options);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1164,7 +1323,7 @@ var ModelTreeModule = class {
 };
 
 // src/modules/markup.module.ts
-function createRequestId4(prefix) {
+function createRequestId5(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 var MarkupModule = class {
@@ -1218,7 +1377,7 @@ var MarkupModule = class {
   }
   getList(options) {
     var _a;
-    const requestId = createRequestId4("markup-list");
+    const requestId = createRequestId5("markup-list");
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1236,7 +1395,7 @@ var MarkupModule = class {
   }
   runRequest(prefix, messageType, eventName, options) {
     var _a;
-    const requestId = createRequestId4(prefix);
+    const requestId = createRequestId5(prefix);
     const timeoutMs = Math.max(1e3, (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 1e4);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1282,7 +1441,7 @@ function createObjectPropertiesError(message, errorStatus) {
   error.errorStatus = errorStatus;
   return error;
 }
-function createRequestId5(prefix) {
+function createRequestId6(prefix) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 function normalizeNodeIds(nodeIds) {
@@ -1300,7 +1459,7 @@ var ObjectPropertiesModule = class {
   getByNodeIds(nodeIds, options) {
     var _a;
     const normalizedNodeIds = normalizeNodeIds(nodeIds);
-    const requestId = createRequestId5("object_properties");
+    const requestId = createRequestId6("object_properties");
     if (normalizedNodeIds.length === 0) {
       return Promise.resolve({
         requestId,
@@ -1413,6 +1572,30 @@ var Viewer3D = class {
           });
           break;
         }
+        case "viewer-node-locked-state" /* NODE_LOCKED_STATE */: {
+          const payload = data.payload;
+          if (!payload) break;
+          this._emit("node:locked-state", {
+            requestId: payload.requestId ? String(payload.requestId) : void 0,
+            persistentIds: Array.isArray(payload.persistentIds) ? payload.persistentIds.map(String) : [],
+            treeNodeIds: Array.isArray(payload.treeNodeIds) ? payload.treeNodeIds.map(String) : [],
+            renderedNodeIds: Array.isArray(payload.renderedNodeIds) ? payload.renderedNodeIds.map(String) : [],
+            timestamp: Number(payload.timestamp) || Date.now()
+          });
+          break;
+        }
+        case "viewer-node-locked-state-change" /* NODE_LOCKED_STATE_CHANGE */: {
+          const payload = data.payload;
+          if (!payload) break;
+          this._emit("node:locked-state-change", {
+            requestId: payload.requestId ? String(payload.requestId) : void 0,
+            persistentIds: Array.isArray(payload.persistentIds) ? payload.persistentIds.map(String) : [],
+            treeNodeIds: Array.isArray(payload.treeNodeIds) ? payload.treeNodeIds.map(String) : [],
+            renderedNodeIds: Array.isArray(payload.renderedNodeIds) ? payload.renderedNodeIds.map(String) : [],
+            timestamp: Number(payload.timestamp) || Date.now()
+          });
+          break;
+        }
         case "viewer-pan-change" /* PAN_CHANGE */:
           this._emit("interaction:pan-change", {
             enabled: Boolean((_a = data.payload) == null ? void 0 : _a.enabled)
@@ -1636,6 +1819,7 @@ var Viewer3D = class {
       }
     };
     this.camera = new CameraModule(this);
+    this.display = new DisplayModule(this);
     this.interaction = new InteractionModule(this);
     this.node = new NodeModule(this);
     this.files = new FilesModule(this);
@@ -1763,6 +1947,13 @@ var Viewer3D = class {
       if (((_a = this.options.ui) == null ? void 0 : _a.loadingIndicator) === false) {
         parsedUrl.searchParams.set("loadingIndicator", "false");
       }
+      const initialBackground = this.normalizeInitialBackground();
+      if (initialBackground) {
+        parsedUrl.searchParams.set(
+          "initialBackground",
+          JSON.stringify(initialBackground)
+        );
+      }
       return parsedUrl.toString();
     } catch {
       return url;
@@ -1795,6 +1986,11 @@ var Viewer3D = class {
       {}
     );
   }
+  normalizeInitialBackground() {
+    const initialBackground = this.options.initialBackground;
+    if (!initialBackground) return null;
+    return normalizeInitialBackground(initialBackground);
+  }
   // ===== typed internal events used by modules =====
   _on(event, cb) {
     return this.emitter.on(event, cb);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3dviewer-sdk",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [