@roomle/web-sdk 4.2.0-alpha.7 → 4.3.0-alpha.1

package/lib/roomle-headless.d.ts

@@ -2016,6 +2016,7 @@ export declare class ConfiguratorViewModel implements ConfiguratorKernelCallback
     private _subPartObject;
     private _subPartGuard;
     protected _components: Map<number, RoomleComponent>;
+    private _componentsWithOutdatedGeometry;
     private _previews;
     protected _componentNumberOfPossibleChildren: Map<number, number>;
     protected _componentFactory: RoomleComponentFactory;
@@ -2064,6 +2065,7 @@ export declare class ConfiguratorViewModel implements ConfiguratorKernelCallback
     Editor3dGeometryReady(id: number): void;
     Editor3dGeometryNotReady(id: number): void;
     Editor3dPlanObjectConstructionDone(planObjectId: number): void;
+    private _finishPendingPlanObjectConstruction;
     Editor3dPreviewConstructionDone(componentId: number, _objectId: number): void;
     Editor3dSetPreviewAssociations(dockPairs: KernelDockPairPreview[], previewId: number): void;
     componentDeleted(componentId: number): void;
@@ -2097,6 +2099,7 @@ export declare class ConfiguratorViewModel implements ConfiguratorKernelCallback
     protected _generateMesh(runtimeComponentId: number | undefined, geometryId: string | null | undefined, materialId: string | null, vertices: Float32Array, indices: Int32Array, uvCoords: Float32Array, normals: Float32Array, _type?: KernelEnum, _newGeometryInstance?: boolean, materialAttributes?: Record<string, string>): Mesh;
     protected _setMaterial(mesh: Mesh, material: any, _type?: KernelEnum): void;
     constructComponents(planObjectId: number): void;
+    private _takeOutdatedGeometryOf;
     requestSubPartConstruction(partId: number): Promise<Mesh>;
     protected getMeshGenerator(): MeshGenerator;
     setRequestRenderCallback(requestRenderCallback: () => void): void;
@@ -2280,6 +2283,7 @@ export declare const CORE_PLAN_COMPONENT_TYPE: {
 export declare const CORE_PLAN_ROOM_GEOMETRY_MODE: {
     readonly FLOOR: 0;
     readonly ROOM: 1;
+    readonly PLAN: 2;
 };
 
 export declare const CORE_SNAP_STATE: {
@@ -2957,9 +2961,13 @@ export declare interface ExternalObjectAPI {
      */
     loadExternalObjectGroups(groupJson: ExternalGroupData, options: LoadExternalObjectOptions): Promise<LoadExternalObjectGroupResult[]>;
     /**
-     * "loadExternalObjectGroupLayout" creates and loads a group of modules from an article layout.
-     * @param articleLayoutJson The article layout JSON as object.
-     * @param layoutType The article layout type. Only "nobila" is supported at the moment.
+     * "loadExternalObjectGroupLayout" creates and loads groups of modules from an article layout.
+     * @param articleLayoutJson The article layout JSON as object. The layout type "nobila" evaluates
+     * the "shapes" property, the layout type "posGroups" evaluates the "posGroups" property.
+     * For the layout type "posGroups" a group whose id matches a group already loaded in the plan
+     * completely replaces that group; root modules keep their ids when they already exist in the
+     * replaced group, all other ids are regenerated.
+     * @param layoutType The article layout type. "nobila" and "posGroups" are supported.
      * @param options Options for loading the external object group.
      */
     loadExternalObjectGroupLayout(articleLayoutJson: ExternalObjectGroupLayout, layoutType: string, options?: LoadExternalObjectOptions): Promise<LoadExternalObjectGroupResult[]>;
@@ -3056,6 +3064,13 @@ export declare interface ExternalObjectAPI {
      * "getExternalRoomInformation" returns the room information for currently loaded in the plan.
      */
     getExternalRoomInformation(mode?: PlanRoomGeometryMode): Promise<ExternalRoomInformation>;
+    /**
+     * "getExternalObjectPlanContext" returns a consistent snapshot of the external object state:
+     * the master data per library, the room information of all rooms, the articles that can be
+     * used, and all groups currently loaded in the plan.
+     * @param include The sections to include. All sections are returned when omitted or empty.
+     */
+    getExternalObjectPlanContext(include?: HiPlanContextSection[]): Promise<HiPlanContext>;
     /**
      * It generates a snapshot of the external object in the plan without saving any data.
      * By default, the snapshot includes order data, room information, the plan XML, GLBs of the complete scene,
@@ -3130,6 +3145,7 @@ export declare interface ExternalObjectGroup {
 export declare interface ExternalObjectGroupLayout {
     [key: string]: unknown;
     shapes?: ExternalObjectGroupLayoutShape[];
+    posGroups?: PosGroup[];
 }
 
 export declare interface ExternalObjectGroupLayoutArticle {
@@ -3651,8 +3667,9 @@ export declare interface GlueLogic {
     getSaveDataGroups(): Promise<PosGroup[] | null>;
     getSubArticleId(id: string): string | undefined;
     newPosDataFromId(id: string): Promise<PosGroup | undefined>;
-    newPosDataFromArticleLayout(articleLayoutJson: ExternalObjectGroupLayout, layoutType: string, posArticles?: PosArticle[]): Promise<PosGroup | undefined>;
+    createOrReplacePosDataFromArticleLayout(articleLayoutJson: ExternalObjectGroupLayout, layoutType: string, posArticles?: PosArticle[]): Promise<PosGroup | PosGroup[] | undefined>;
     newPosDataFromGroup(posDataJson: PosGroup): Promise<PosGroup>;
+    getPlanContext(include?: HiPlanContextSection[]): Promise<HiPlanContext>;
     getGroupDataForOrder(options: GetGroupDataForOrderOptions): Promise<HiOrderData | null>;
     getMaterialUrl(materialId: string, groupOrModuleId?: string): string | null;
 }
@@ -3812,25 +3829,12 @@ export declare interface HeadlessInitData extends Partial<InitDataDefinition>, P
 }
 
 export declare class HeadlessRoomleSdk {
-    private _planner;
-    private _plannerMain;
-    private _configurator;
-    private _configuratorMain;
-    private _glbViewer;
-    private _glbViewerMain;
-    private _initialized;
-    private _configuratorReady;
-    private _plannerReady;
-    private _glbViewerReady;
-    private _loadedConfigurationId;
-    private _loadedPlanId;
-    private _loadedStaticItemId;
-    private _width;
-    private _height;
-    private _featureFlags?;
-    private _webGpuConfig?;
-    private _webGpu;
+    private readonly _initData;
+    private readonly _webGpuConfig;
+    private readonly _container;
+    private _plannerMainPromise;
     private _loaderQueue;
+    private _loadedScene;
     private _skyboxOriginal;
     /**
      * Create and initialize a headless SDK instance.
@@ -3838,82 +3842,66 @@ export declare class HeadlessRoomleSdk {
      * @returns Initialized SDK instance.
      */
     static create(initData: HeadlessInitData): Promise<HeadlessRoomleSdk>;
-    private _init;
-    private _deepMergeHeadlessInitDefaults;
-    private _registerHeadlessServices;
-    private _makeStubElement;
+    private constructor();
     /**
-     * Boot and initialize the configurator module ahead of first load.
-     * @param initData Optional per-module init overrides.
+     * Mount the configurator inside the planner, booting the planner if needed.
+     * It shares the planner's kernel and scene manager (the planner's own
+     * configure-in-room path) and never loads a scene of its own.
      */
-    prewarmConfigurator(initData?: Partial<InitDataDefinition>): Promise<void>;
+    getHeadlessConfigurator(): Promise<RoomleConfigurator>;
     /**
-     * Boot and initialize the planner module ahead of first load.
-     * @param initData Optional per-module init overrides.
+     * Boot and initialize the headless planner. Optional: every load boots it
+     * on demand.
      */
-    prewarmPlanner(initData?: Partial<InitDataDefinition>): Promise<void>;
+    createHeadlessPlanner(): Promise<void>;
     /**
-     * Boot and initialize the GLB viewer module ahead of first load.
-     * @param initData Optional per-module init overrides.
+     * The first call boots a planner, every other one awaits the same boot promise
+     * so we can only ever have 1 instance.
      */
-    prewarmGlbViewer(initData?: Partial<InitDataDefinition>): Promise<void>;
+    private _getPlannerMain;
+    private _bootPlanner;
+    private _getPlanner;
+    private _getConfigurator;
     /**
-     * Load a saved configuration by **id**, via the RAPI `/configurations/`
-     * endpoint. For an inline configuration string use
-     * {@link loadConfigurationString} instead.
-     * @param configurationId Multi-segment id like `catalog:item:HASH`.
-     * @param initData Optional per-module init overrides for prewarm.
+     * Load a saved configuration by **id**. Like every load it goes through the
+     * planner: `createPlanFromObject` picks the RAPI endpoint from the id shape
+     * (`/items/` for `catalog:item`, `/configurations/` for `catalog:item:HASH`),
+     * so this method, {@link loadConfigurableItemById} and {@link loadStaticItem}
+     * behave the same and only name the caller's intent. For an inline
+     * configuration string use {@link loadConfigurationString} instead.
+     * @param configurationId `catalog:item:HASH`.
      */
-    loadConfiguration(configurationId: RapiId, initData?: Partial<InitDataDefinition>): Promise<void>;
+    loadConfiguration(configurationId: RapiId): Promise<void>;
     /**
      * Load a configuration string directly without querying the RAPI (`{"componentId":"catalog:item",…}`)
      * To load a configuration by ID, use {@link loadConfiguration}
      */
-    loadConfigurationString(configuration: string, initData?: Partial<InitDataDefinition>): Promise<void>;
+    loadConfigurationString(configuration: string): Promise<void>;
     /**
-     * Load a configurable item via the RAPI `/items/` endpoint.
+     * Load a configurable item by id. Same path as {@link loadConfiguration};
+     * the name states the intent.
      * @param itemId Single-segment id like `catalog:item`.
-     * @param initData Optional per-module init overrides for prewarm.
      */
-    loadConfigurableItemById(itemId: RapiId, initData?: Partial<InitDataDefinition>): Promise<void>;
-    private _loadIntoConfigurator;
+    loadConfigurableItemById(itemId: RapiId): Promise<void>;
     /**
-     * Load a static (non-configurable) item via the GLB viewer.
+     * Load a static (non-configurable) item. Same path as
+     * {@link loadConfiguration}; the kernel decides static vs. configurable.
      * @param staticItemId Catalog item id whose RAPI record has no `configuration`.
-     * @param initData Optional per-module init overrides for prewarm.
-     */
-    loadStaticItem(staticItemId: string, initData?: Partial<InitDataDefinition>): Promise<void>;
-    /**
-     * GLB-loaded scenes commonly contain hundreds of thousands of triangles
-     * (high-poly furniture/cars). With the default 1024² shadow map those
-     * triangles cast a self-shadow pattern back onto themselves that the
-     * shadow comparison can't resolve cleanly — it appears as a dense
-     * triangle/herringbone overlay covering every PBR-shaded surface
-     * (visible on flat-coloured car bodies, wood slats, etc.). The
-     * artifact is specific to headless's GL backend; in the browser the
-     * same scene renders fine.
-     *
-     * Walking the freshly-loaded scene and clearing `castShadow` on every
-     * mesh removes the cause of the acne while keeping `receiveShadow`,
-     * so static items still pick up shadows from external casters and
-     * full PBR direct-light shading is preserved.
      */
-    private _suppressGlbSelfShadowing;
-    loadObject(id: string, initData?: Partial<InitDataDefinition>): Promise<void>;
+    loadStaticItem(staticItemId: string): Promise<void>;
+    loadObject(id: string): Promise<void>;
     /**
      * Load a plan into the planner.
      * @param planId Plan id (no colons).
-     * @param initData Optional per-module init overrides for prewarm.
      */
-    loadPlan(planId: string, initData?: Partial<InitDataDefinition>): Promise<void>;
+    loadPlan(planId: string): Promise<void>;
     /**
      * Load plan XML string directly in the planner.
      * @param xml Plan XML (`<plan version="2">…</plan>`).
-     * @param initData Optional per-module init overrides for prewarm.
      */
-    loadPlanXml(xml: string, initData?: Partial<InitDataDefinition>): Promise<void>;
+    loadPlanXml(xml: string): Promise<void>;
     private _loadIntoPlanner;
-    private _inlineSceneId;
+    private _load;
     /**
      * Serialises concurrent load operations using a promise-chain queue.
      * Each call chains its task onto the previous queue tail so they run
@@ -3922,28 +3910,6 @@ export declare class HeadlessRoomleSdk {
      * always advanced in a settled state).
      */
     private _withLoader;
-    /**
-     * Wait for the active scene to fire its onReadyForRender callback —
-     * fired by each scene manager once `_itemsLoaded` (planner) /
-     * `loadConfiguration` (configurator) / `loadStaticItem` (GLB viewer)
-     * has finished constructing the scene and queued its materials. The
-     * callback is armed via {@link _armOnReadyForRender} *before* the load
-     * begins so synchronous firings (the GLB viewer does this) are still
-     * caught.
-     */
-    private _settleScene;
-    /**
-     * Pre-arms an onReadyForRender listener on the *global* callback (shared
-     * across configurator/planner/GLB viewer) so that it captures even
-     * synchronous firings during the upcoming load. Restores the previous
-     * callback after firing. Using the global callback rather than each
-     * module's api.callbacks is necessary because the GLB viewer only fires
-     * the global one ([glb-viewer-scene-manager.ts:355](packages/web-sdk/packages/glb-viewer-core/src/webgl/glb-viewer-scene-manager.ts:355)).
-     */
-    private _armOnReadyForRender;
-    private _onReadyForRenderArmed;
-    private _getPlannerListenerInfo;
-    private _getConfiguratorListenerInfo;
     /**
      * Export the active scene as GLB.
      * @param outputPath Optional file path to write the buffer to.
@@ -3956,16 +3922,7 @@ export declare class HeadlessRoomleSdk {
      * @returns The USDZ bytes as an ArrayBuffer.
      */
     exportUSDZ(outputPath?: string): Promise<ExportResult>;
-    /**
-     * Returns the active top-level API (planner or configurator) based on what
-     * was last loaded. `loadPlan()` and `loadConfiguration()` are mutually
-     * exclusive — each one nulls the other's id — so this resolves cleanly.
-     */
-    private _getActiveApi;
-    /**
-     * Returns the scene manager of whichever module is active. All exporters
-     * route through here so plan-mode and config-mode share a single code path.
-     */
+    private _requireLoadedScene;
     private _getActiveSceneManager;
     setEnvironmentMap(url: string, options?: EnvironmentMapOptions): Promise<void>;
     resetEnvironmentMap(options?: EnvironmentMapOptions): Promise<void>;
@@ -3973,6 +3930,8 @@ export declare class HeadlessRoomleSdk {
     private _getEnvironmentSceneManager;
     setSkybox(url: string): Promise<void>;
     resetSkybox(): void;
+    private _useEnvironmentGeometry;
+    private _withLoadedScene;
     private _export;
     /**
      * Render a perspective screenshot preserving the scene background.
@@ -3997,7 +3956,9 @@ export declare class HeadlessRoomleSdk {
         height: number;
     }>;
     /**
-     * Render a top-down image of the scene. Not supported for static items.
+     * Render a top-down image of the scene. Not covered by tests for static
+     * items (RML-17789): the GLB viewer used to refuse them, the planner path
+     * does not, and nobody has verified the output yet.
      * @param outputPath Optional file path to write the PNG to.
      * @param options ssaa, size, showDimensions.
      * @returns Data URL plus final image dimensions.
@@ -4007,18 +3968,9 @@ export declare class HeadlessRoomleSdk {
         width: number;
         height: number;
     }>;
-    private _resolveTopImage;
-    private _getRenderDimensions;
-    private _resolveImageDataUrl;
-    private _writeDataUrlToFile;
-    private _rawPixelsToPngDataUrl;
-    /** Downscale a data URL image to target dimensions using high-quality filtering. */
-    private _ssaaDownscale;
-    getConfiguratorApi(): RoomleConfigurator<readonly []>;
-    getPlannerApi(): RoomlePlanner<readonly []>;
-    /** Destroy any prewarmed configurator, planner, and GLB viewer modules. */
+    getConfiguratorApi(): Promise<RoomleConfigurator>;
+    getPlannerApi(): Promise<RoomlePlanner>;
     destroy(): Promise<void>;
-    private _ensureInitialized;
 }
 
 export declare interface HelpLineType {
@@ -4101,6 +4053,15 @@ export declare interface HiObjectSelectionApi {
     selectionChanged(selectionMode: SELECTION_MODE, objectType: CallbackObjectType, payload: SelectionPayload, _payloadPromise: Promise<SelectionPayload>, _planElementViewModel: PlanElementViewModel): void;
 }
 
+export declare interface HiPlanContext {
+    masterData?: Record<string, MasterData>;
+    rooms?: ExternalRoomInformation;
+    articles?: PosArticle[];
+    groups?: PosGroup[];
+}
+
+export declare type HiPlanContextSection = 'masterData' | 'rooms' | 'articles' | 'groups';
+
 export declare class HiTagCatalogCallbacks implements Context {
     _creator_: string;
     private _glueLogic;
@@ -5142,6 +5103,7 @@ export declare interface LoadExternalObjectGroupResult {
 
 export declare interface LoadExternalObjectOptions {
     reason?: HiLoadObjectReason;
+    applyGroupPosition?: boolean;
     findFreeSpaceInPlan?: boolean;
     moduleIdMap?: Array<{
         originalModuleId: string;
@@ -5820,6 +5782,7 @@ export declare const PLAN_ELEMENT_CHANGE_TYPES: {
 export declare const PLAN_ROOM_GEOMETRY_MODE: {
     readonly FLOOR: "floor";
     readonly ROOM: "room";
+    readonly PLAN: "plan";
 };
 
 export declare abstract class PlanElement extends AbstractModelWrapper {
@@ -6380,6 +6343,7 @@ export declare class PlannerSceneEventHandler extends SceneEventHandler<SceneEve
     private _move;
     hasSelection(): boolean;
     selectPlanElement(planElement: PlanElementViewModel): Promise<void>;
+    selectPlanElementAfterObjectModeChange(planElement: PlanElementViewModel): void;
     protected _interaction(_forceRender?: boolean): void;
     addComponentDragInHandler(planViewModel: PlanElementViewModel): void;
     enableSnapping(): void;
@@ -6514,6 +6478,7 @@ export declare class PlannerSceneManager extends ConfiguratorSceneManager implem
     private _setCameraPosition;
     private _resetCameraPosition;
     selectPlanObject(runtimeId: number): Promise<void>;
+    selectPlanObjectAfterObjectModeChange(runtimeId: number): void;
     backToPlanner(): void;
     private _getYRotationOfObject;
     loadStaticPlanObjects(): void;
@@ -8292,6 +8257,7 @@ export declare interface RoomleComponent extends RoomleEventedObject3D {
     animationValueMap?: AnimationValueMap;
     get childComponents(): RoomleComponent[];
     get parentComponent(): RoomleComponent | null;
+    get rootComponent(): RoomleComponent;
     replaceMeshes(meshes: Mesh[]): void;
     addMesh(mesh: Mesh, transform?: Float32Array): void;
     removeMesh(mesh: Mesh): void;
@@ -9321,6 +9287,14 @@ export declare class RoomlePlanner<P extends readonly PluginName[] = readonly []
      * return the object runtime id
      */
     createPlanFromObject(id: RapiId, position?: Position3, rotation?: number): Promise<number>;
+    /**
+     * Creates a plan holding a single object built from a configuration string
+     * @param configuration configuration string (`{"componentId":"catalog:item",…}`).
+     * @param position XYZ
+     * @param rotation deg
+     */
+    createPlanFromConfigurationString(configuration: string, position?: Position3, rotation?: number): Promise<number>;
+    private _createPlanFromElement;
     loadPlanXml(xml: string, options?: InitDataDefinition & GlobalInitDataDefinition): Promise<void>;
     /**
      * Creates 2D elevation plans of the current plan, one per elevation view.
@@ -9678,6 +9652,7 @@ export declare class RoomlePlanner<P extends readonly PluginName[] = readonly []
     private _loadExternalObjectGroupInConfigurator;
     private _loadExternalObjectGroupInPlanner;
     private _updateExternalObjectRootModuleSelection;
+    private _mergeAndSelectExternalObjectGroup;
     private _loadOrUpdateExternalObjectGroup;
     private _interactionBeforeLoadingExternalObjectGroups;
     private _interactionAfterLoadingExternalObjectGroups;
@@ -9699,6 +9674,7 @@ export declare class RoomlePlanner<P extends readonly PluginName[] = readonly []
     openOrCloseGeometryOfExternalObject(groupIdOrRootModuleId: string, _subModuleId: string | null, open: boolean, animate: boolean): void;
     _selectExternalObjectGroup(groupId: string, switchToPlanner: boolean): Promise<void>;
     getExternalObjectGroups(): Promise<object[]>;
+    getExternalObjectPlanContext(include?: HiPlanContextSection[]): Promise<HiPlanContext>;
     getExternalRoomInformation(mode?: PlanRoomGeometryMode): Promise<ExternalRoomInformation>;
     /**
      * Highlights a product in the planner.
@@ -10304,6 +10280,7 @@ export declare abstract class SceneManager implements Context, LifeCycleCallback
     private _clock;
     private _delta;
     protected _renderLoopFunction: (() => void) | null;
+    private _renderLoopFunctionApplied;
     protected _renderListener: (() => void) | null;
     protected _stopRendering: boolean;
     protected _roomleRenderer: GenericRoomleRenderer | null;
@@ -10320,6 +10297,12 @@ export declare abstract class SceneManager implements Context, LifeCycleCallback
     protected abstract createCameraControl(mode: Enumify_2<typeof CAMERA_TYPE>, offset: CanvasOffset): void;
     protected abstract _getInputManager(): InputManager;
     get cameraBehaviour(): CameraBehaviour;
+    protected _scheduleRenderLoopFunction(renderLoopFunction: () => void): void;
+    /**
+     * Resolves the next time the render loop applies a scheduled function, so arm
+     * it **before** triggering the work whose mutation you are waiting for.
+     */
+    whenRenderLoopFunctionApplied(): Promise<void>;
     abstract sceneChanged(): void;
     abstract getBounds(): Box3 | null;
     abstract getGeometryBounds(): Box3 | null;
@@ -11235,6 +11218,7 @@ export declare class WebGpuConfig implements WebGpuConfigDefinition {
     topLight: WebGpuTopLightConfig;
     groundReflection: WebGpuGroundReflectionConfig;
     fog: WebGpuFogConfig;
+    ssgi: WebGpuSSGIConfig;
     toneMapping: WebGpuToneMapping;
     toneMappingExposure: number;
 }
@@ -11273,6 +11257,10 @@ export declare interface WebGpuConfigDefinition {
      * @description Visual configuration for the WebGPU fog.
      */
     fog?: WebGpuFogConfigDefinition;
+    /**
+     * @description Visual configuration for the WebGPU screen space global illumination (SSGI) effect.
+     */
+    ssgi?: WebGpuSSGIConfigDefinition;
     /**
      * @description Tone mapping operator applied by the WebGPU renderer.
      * @default 'none'
@@ -11353,6 +11341,28 @@ export declare interface WebGpuGroundReflectionConfigDefinition {
     endFadeout?: number;
 }
 
+export declare class WebGpuSSGIConfig implements WebGpuSSGIConfigDefinition {
+    giDenoiseRadius: number;
+    aoDenoiseRadius: number;
+}
+
+export declare interface WebGpuSSGIConfigDefinition {
+    /**
+     * @description Radius of the denoising filter applied to the indirect lighting.
+     * Higher values produce a stronger denoising effect, which can help reduce noise
+     * in the indirect lighting but may also blur fine details.
+     * @default 20
+     */
+    giDenoiseRadius?: number;
+    /**
+     * @description Radius of the denoising filter applied to the ambient occlusion (AO) pass.
+     * Higher values produce a stronger denoising effect, which can help reduce noise
+     * in the AO but may also blur fine details.
+     * @default 10
+     */
+    aoDenoiseRadius?: number;
+}
+
 export declare type WebGpuToneMapping = Enumify_2<typeof WEBGPU_TONE_MAPPINGS>;
 
 export declare class WebGpuTopLightConfig implements WebGpuTopLightConfigDefinition {