fix(editor): swap models in save() without blank-frame flicker (#208)

Reorder editor.save() to load and add the replacement model before tearing down the outgoing model's visuals. Adds dispose({ keepInScene }), finalizeDispose() and MaterialManager.releaseModelSlot() as the two-phase deferred-dispose mechanism. Closes #207.

Author: rihokirss

packages/fragments/src/FragmentsModels/src/edit/edit-helper.ts

@@ -92,10 +92,12 @@ export class EditHelper {
     const camera = model.camera || undefined;
     const newModelBuffer = await model._save();
 
-    // Dispose all model
-    await model.dispose();
+    // Free up the modelId slot in the worker + registries, but keep the
+    // model's THREE object, tiles and materials in scene so the user does
+    // not see a blank frame while the new model loads.
+    await model.dispose({ keepInScene: true });
 
-    // Add new model
+    // Load new model with the same id (the slot is now free).
     const newModel = await this._fragments.load(newModelBuffer as any, {
       modelId,
       raw: true,
@@ -109,6 +111,9 @@ export class EditHelper {
       parent.add(newModel.object);
     }
 
+    // New model is in scene now. Tear down the old visuals.
+    model.finalizeDispose();
+
     // Return actions (e.g. to create action history, control z, etc.)
     return requests;
   }

packages/fragments/src/FragmentsModels/src/model/data-manager.ts

@@ -19,10 +19,20 @@ export class DataManager {
     meshes: MeshManager,
     alignments: AlignmentsManager,
     grids: GridsManager,
+    options?: { keepInScene?: boolean },
   ) {
     meshes.list.delete(model.modelId);
     await this.requestModelDelete(model);
     model.threads.delete(model.modelId);
+    if (options?.keepInScene) {
+      // Free the modelId slot in the shared MaterialManager so the
+      // replacement model can register its own definitions without
+      // appending to ours (which would corrupt material indices). The
+      // actual THREE materials in `list` stay alive so the outgoing
+      // tiles keep rendering until `finalizeDispose` runs.
+      meshes.materials.releaseModelSlot(model.modelId);
+      return;
+    }
     model.object.removeFromParent();
     this.deleteAllTiles(model);
     meshes.materials.dispose(model.modelId);

packages/fragments/src/FragmentsModels/src/model/fragments-model.ts

@@ -224,8 +224,15 @@ export class FragmentsModel {
   /**
    * Dispose the model. Use this when you're done with the model.
    * If you use the {@link FragmentsModels.dispose} method, this will be called automatically for all models.
-   */
-  async dispose() {
+   *
+   * @param options.keepInScene - If true, frees the model's worker slot,
+   *   registry entries and shared MaterialManager slot but leaves the THREE
+   *   object, tiles, materials in `list`, alignments and grids in place.
+   *   Caller must finalize the visual cleanup later via
+   *   {@link finalizeDispose}. Used by `editor.save()` to swap in a freshly
+   *   loaded model without a blank frame.
+   */
+  async dispose(options?: { keepInScene?: boolean }) {
     this._isLoaded = false;
     this.visibleItems.clear();
     this.onViewUpdated.reset();
@@ -234,9 +241,35 @@ export class FragmentsModel {
       this._meshManager,
       this._alignmentsManager,
       this._gridsManager,
+      options,
     );
   }
 
+  /**
+   * Finalize a deferred dispose. Removes the THREE object from its parent,
+   * tears down tile meshes (geometry only — materials are shared via the
+   * MaterialManager and may be reused by a replacement model under the
+   * same modelId), and disposes the model's alignments and grids.
+   *
+   * Only call this after `dispose({ keepInScene: true })`. The tile map
+   * is cleared with events disabled to bypass the onBeforeDelete listener
+   * registered in the constructor (which would otherwise dispose tile
+   * materials).
+   */
+  finalizeDispose() {
+    this.object.removeFromParent();
+
+    this.tiles.eventsEnabled = false;
+    for (const [, mesh] of this.tiles) {
+      this.object.remove(mesh);
+      mesh.geometry.dispose();
+    }
+    this.tiles.clear();
+
+    this._alignmentsManager.dispose();
+    this._gridsManager.dispose();
+  }
+
   /**
    * Get the spatial structure of the model.
    */

packages/fragments/src/FragmentsModels/src/model/material-manager.ts

@@ -49,6 +49,17 @@ export class MaterialManager {
     this._modelMaterialMapping.delete(modelId);
   }
 
+  /**
+   * Release a model's slot in the per-model definitions and mapping tables
+   * without disposing the underlying THREE materials in `list`. Used by
+   * `editor.save()` so a fresh model can register under the same modelId
+   * while the outgoing model's tiles still render normally.
+   */
+  releaseModelSlot(modelId: string) {
+    this._definitions.delete(modelId);
+    this._modelMaterialMapping.delete(modelId);
+  }
+
   get(data: MaterialDefinition, request: any) {
     const { modelId, objectClass, currentLod, templateId } = request;
     if (!(modelId && objectClass !== undefined && currentLod !== undefined)) {