@mlightcad/cad-simple-viewer 1.5.0 → 1.5.2

package/lib/view/AcTrView2d.js

@@ -71,14 +71,15 @@ var __values = (this && this.__values) || function(o) {
     };
     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
 };
-import { acdbHostApplicationServices, AcDbRasterImage, AcDbRay, AcDbSysVarManager, AcDbViewport, AcDbXline, AcGeBox2d, AcGePoint2d, log } from '@mlightcad/data-model';
+import { acdbHostApplicationServices, AcDbMText, AcDbRasterImage, AcDbRay, AcDbSysVarManager, AcDbViewport, AcDbXline, AcGeBox2d, AcGePoint2d, log } from '@mlightcad/data-model';
 import { AcDbSystemVariables } from '@mlightcad/data-model';
 import { AcTrEntity, AcTrGroup, AcTrRenderer, AcTrViewportView, getMaterialMetadata, hasByLayerBinding, setMaterialMetadata } from '@mlightcad/three-renderer';
 import * as THREE from 'three';
 import Stats from 'three/examples/jsm/libs/stats.module';
 import { CSS2DRenderer } from 'three/examples/jsm/renderers/CSS2DRenderer.js';
 import { AcApDocManager, AcApSettingManager } from '../app';
-import { AcEdBaseView, AcEdConditionWaiter, AcEdCorsorType, AcEdViewMode, applyUiThemeFromBackground, eventBus, resolvePointerSelectionAction } from '../editor';
+import { AcEdBaseView, AcEdConditionWaiter, AcEdCorsorType, AcEdMTextEditor, AcEdOpenMode, AcEdViewMode, eventBus, resolvePointerSelectionAction } from '../editor';
+import { isModelSpaceDatabase, MODEL_SPACE_BACKGROUND, readLayoutBackgroundColor } from '../editor/global/AcEdUiColor';
 import { AcTrGeometryUtil } from '../util';
 import { AcTrLayoutView } from './AcTrLayoutView';
 import { AcTrLayoutViewManager } from './AcTrLayoutViewManager';
@@ -88,7 +89,7 @@ import { AcTrScene } from './AcTrScene';
  * Default view option values
  */
 export var DEFAULT_VIEW_2D_OPTIONS = {
-    background: 0x000000
+    background: MODEL_SPACE_BACKGROUND
 };
 /**
  * A 2D CAD viewer component that renders CAD drawings using Three.js.
@@ -124,7 +125,7 @@ var AcTrView2d = /** @class */ (function (_super) {
     function AcTrView2d(options) {
         if (options === void 0) { options = DEFAULT_VIEW_2D_OPTIONS; }
         var _this = this;
-        var _a;
+        var _a, _b;
         var mergedOptions = __assign(__assign({}, DEFAULT_VIEW_2D_OPTIONS), options);
         var container = (_a = mergedOptions.container) !== null && _a !== void 0 ? _a : document.createElement('div');
         mergedOptions.container = container;
@@ -145,6 +146,37 @@ var AcTrView2d = /** @class */ (function (_super) {
          * A value of `null` indicates that no animation frame is currently scheduled.
          */
         _this._rafId = null;
+        /**
+         * Block table record ids of layouts whose entities are currently being
+         * batch-converted into the scene. Used by
+         * {@link AcTrView2d.loadLayoutEntitiesIfNeeded} to guard against
+         * re-entrant calls before the `setTimeout` callback flips
+         * `AcTrLayout.isLoaded` to `true`, which would otherwise duplicate
+         * entities when the same layout tab is clicked twice in quick succession.
+         */
+        _this._loadingLayouts = new Set();
+        /**
+         * Block table record ids of layouts that have already received an
+         * initial zoom-to-fit. Used by the `layoutSwitched` handler to apply
+         * the auto-zoom **only on the first user visit** to each layout, and
+         * to preserve the camera state on subsequent visits (matches AutoCAD's
+         * per-tab view persistence).
+         *
+         * Cannot be inferred from `_layoutViewManager.has(btrId)` because
+         * `addLayout` pre-creates an `AcTrLayoutView` for every layout in the
+         * DWG at document load time — by the time the user clicks a layout
+         * tab the view already exists, so "first existence of view" is
+         * always false. This set tracks the orthogonal question "has the user
+         * actually focused on this layout before?".
+         *
+         * Marked from two entry points:
+         *  - `onAfterOpenDocument` (via `markLayoutAsInitialized`): the
+         *    document's startup layout is initialized externally, so we don't
+         *    auto-zoom again when the user clicks back to it.
+         *  - `layoutSwitched` handler: after the first user-driven switch
+         *    completes its initial zoom-to-fit.
+         */
+        _this._initializedLayouts = new Set();
         _this.animate = function () {
             var _a;
             _this._rafId = requestAnimationFrame(_this.animate);
@@ -152,14 +184,15 @@ var AcTrView2d = /** @class */ (function (_super) {
                 render: _this._renderer,
                 camera: _this.internalCamera
             });
-            if (!_this._isDirty)
+            var stillLoading = _this._numOfEntitiesToProcess > 0;
+            if (!_this._isDirty && !stillLoading)
                 return;
-            _this._layoutViewManager.render(_this._scene);
+            var needsRedraw = _this._layoutViewManager.render(_this._scene);
             if (_this.internalCamera) {
                 _this._css2dRenderer.render(_this._scene.internalScene, _this.internalCamera);
             }
             (_a = _this._stats) === null || _a === void 0 ? void 0 : _a.update();
-            _this._isDirty = false;
+            _this._isDirty = stillLoading || needsRedraw;
         };
         if (options.calculateSizeCallback) {
             _this.setCalculateSizeCallback(options.calculateSizeCallback);
@@ -177,46 +210,26 @@ var AcTrView2d = /** @class */ (function (_super) {
             });
         });
         _this._scene = _this.createScene();
-        // Initialize background color through setter to keep renderer/cursor/foreground in sync.
-        _this.backgroundColor = mergedOptions.background || 0x000000;
+        // Initialize background color through setter to keep renderer/cursor in sync.
+        _this.backgroundColor = (_b = mergedOptions.background) !== null && _b !== void 0 ? _b : MODEL_SPACE_BACKGROUND;
         _this._stats = _this.createStats(AcApSettingManager.instance.isShowStats);
-        // Two sysvars can drive the canvas background:
-        //
-        // - WHITEBKCOLOR (boolean): the low-level "is the paper white?" flag
-        //   that the View has always honoured.
-        // - COLORTHEME (number): the AutoCAD-standard theme selector where
-        //   0 = dark theme (black bg) and 1 = light theme (white bg).
-        //
-        // The Vue composable `useDark` (cad-viewer) toggles only COLORTHEME
-        // when the user flips the theme.  Without this bridge, toggling the
-        // UI theme left WHITEBKCOLOR stale and the canvas kept its previous
-        // background even though `changeForeground` had been fired through
-        // MTEXT/line inversion — producing e.g. a black canvas in light mode
-        // or a white canvas in dark mode.
-        //
-        // Listening to both sysvars keeps either entry point working.  The
-        // two remain independent (settable in isolation) because setting
-        // `this.backgroundColor` is idempotent and the handler for each
-        // sysvar only fires when that specific variable changes.
-        AcDbSysVarManager.instance().events.sysVarChanged.addEventListener(function (args) {
+        // Layout background sysvars drive the canvas clear colour and ACI-7
+        // inversion (`MODELBKCOLOR` for model space, `PAPERBKCOLOR` for the
+        // active layout). `COLORTHEME` only affects UI chrome — see
+        // `useDark` / `AcEdUiTheme`, not the renderer foreground.
+        var sysVarManager = AcDbSysVarManager.instance();
+        var modelBkVar = AcDbSystemVariables.MODELBKCOLOR.toLowerCase();
+        var paperBkVar = AcDbSystemVariables.PAPERBKCOLOR.toLowerCase();
+        sysVarManager.events.sysVarChanged.addEventListener(function (args) {
             var nameLower = args.name.toLowerCase();
-            if (nameLower === AcDbSystemVariables.WHITEBKCOLOR.toLowerCase()) {
-                var useWhiteBackgroundColor = args.newVal;
-                _this.backgroundColor = useWhiteBackgroundColor ? 0xffffff : 0;
-            }
-            else if (nameLower === AcDbSystemVariables.COLORTHEME.toLowerCase()) {
-                // COLORTHEME is registered with type 'number' in the data-model
-                // (0 = dark, 1 = light), but the sysvar bus does not strictly
-                // coerce values.  Normalise defensively so plugins setting the
-                // value as a string or boolean still behave correctly.
-                var newVal = args.newVal;
-                var isLight = typeof newVal === 'number'
-                    ? newVal === 1
-                    : typeof newVal === 'boolean'
-                        ? newVal
-                        : String(newVal).toLowerCase() === 'light' ||
-                            String(newVal) === '1';
-                _this.backgroundColor = isLight ? 0xffffff : 0;
+            if (nameLower === modelBkVar || nameLower === paperBkVar) {
+                var isModelSpace = _this.isModelSpaceLayout(args.database);
+                var applies = (nameLower === modelBkVar && isModelSpace) ||
+                    (nameLower === paperBkVar && !isModelSpace);
+                if (!applies) {
+                    return;
+                }
+                _this.applyCanvasBackground(readLayoutBackgroundColor(args.database, isModelSpace));
             }
         });
         AcApSettingManager.instance.events.modified.addEventListener(function (args) {
@@ -228,7 +241,9 @@ var AcTrView2d = /** @class */ (function (_super) {
         var selectionStartCanvas = null;
         var selectionPreviewEl = null;
         var canHandleSelectionGesture = function () {
-            return _this.mode === AcEdViewMode.SELECTION && !_this.editor.isActive;
+            return (_this.mode === AcEdViewMode.SELECTION &&
+                !_this.editor.isActive &&
+                !AcEdMTextEditor.getActiveInputBox());
         };
         var clearSelectionPreview = function () {
             selectionPreviewEl === null || selectionPreviewEl === void 0 ? void 0 : selectionPreviewEl.remove();
@@ -302,6 +317,16 @@ var AcTrView2d = /** @class */ (function (_super) {
             selectionStartWcs = null;
             selectionStartCanvas = null;
         });
+        _this.canvas.addEventListener('dblclick', function (e) {
+            if (e.button !== 0)
+                return;
+            if (!canHandleSelectionGesture())
+                return;
+            if (AcApDocManager.instance.curDocument.openMode !== AcEdOpenMode.Write) {
+                return;
+            }
+            void _this.openPickedMTextEditor(e);
+        });
         // When using OrbitControls in THREE.js, it attaches its own event listeners to the DOM elements,
         // such as the canvas or the entire document. This can interfere with other event listeners you
         // add, including the keydown event.
@@ -333,10 +358,51 @@ var AcTrView2d = /** @class */ (function (_super) {
             }
         });
         acdbHostApplicationServices().layoutManager.events.layoutSwitched.addEventListener(function (args) {
-            _this.activeLayoutBtrId = args.layout.blockTableRecordId;
-            _this.createLayoutViewIfNeeded(args.layout.blockTableRecordId);
-            _this.loadLayoutEntitiesIfNeeded(args.layout.blockTableRecordId);
+            var btrId = args.layout.blockTableRecordId;
+            // "First visit" is tracked separately from view existence because
+            // `addLayout` pre-creates an `AcTrLayoutView` for every layout in
+            // the DWG at load time — `_layoutViewManager.has(btrId)` is
+            // therefore `true` even for layouts the user has never focused
+            // on, and "first visit" computed from it would always be false.
+            // We use a dedicated set instead, marked here on first switch and
+            // also from `markLayoutAsInitialized` when the document opens
+            // straight into a layout (AcApDocManager has already framed it).
+            // Each AcTrLayoutView owns its own camera, so on subsequent
+            // visits the previous camera state is naturally restored and we
+            // must NOT zoom-to-fit again — that would be jarring and
+            // diverges from how AutoCAD preserves per-tab view state.
+            var isFirstVisit = !_this._initializedLayouts.has(btrId);
+            _this._initializedLayouts.add(btrId);
+            // Clear measurement overlays before swapping layouts.
+            // Measurements are screen/coordinate-anchored — their dimension
+            // text, hatch indicators, and HTML overlays were laid out in
+            // the previous layout's WCS (paper coords, ~unit scale) and
+            // would render at nonsense positions in a different layout
+            // (model WCS is typically O(10^5) larger, paper layouts use
+            // their own sheet coords). Selection state is intentionally
+            // **not** cleared here: it is entity-id-based and the same
+            // entity stays selected wherever it is rendered (the model
+            // entity drilled through a paper viewport remains visually
+            // selected when the user returns to model space, matching
+            // AutoCAD desktop's behaviour).
+            //
+            // Dynamic import avoids a circular dependency: the cleanup
+            // module already imports `AcTrView2d` for its
+            // `htmlTransientManager` cast, so a static import here would
+            // create a cycle. The cost (one extra microtask) is
+            // negligible for a layout switch.
+            void import('../command/measure/AcApClearMeasurementsCmd').then(function (_a) {
+                var clearAllMeasurements = _a.clearAllMeasurements;
+                return clearAllMeasurements(_this);
+            });
+            _this.activeLayoutBtrId = btrId;
+            _this.createLayoutViewIfNeeded(btrId);
+            _this.loadLayoutEntitiesIfNeeded(btrId);
+            _this.refreshCanvasBackgroundForActiveLayout();
             _this._isDirty = true;
+            if (isFirstVisit) {
+                _this.applyInitialZoom(btrId, args.layout);
+            }
         });
         _this._css2dRenderer = new CSS2DRenderer();
         _this._css2dRenderer.setSize(_this.width, _this.height);
@@ -466,18 +532,49 @@ var AcTrView2d = /** @class */ (function (_super) {
          * @param value - The background color as a 24-bit hexadecimal RGB number
          */
         set: function (value) {
-            this._renderer.setClearColor(value);
-            this._renderer.changeForeground(value == 0 ? 0xffffff : 0);
-            // Store the canvas colour for theme-sensitive materials created after this
-            // point. `changeForeground` above keeps ACI 7 linework and hatches visible.
-            this._renderer.currentBackgroundColor = value;
-            this.editor.setCursorColor(value == 0 ? 'white' : 'black');
-            applyUiThemeFromBackground(value);
-            this._isDirty = true;
+            this.applyCanvasBackground(value);
         },
         enumerable: false,
         configurable: true
     });
+    /**
+     * Applies canvas background colour from layout background sysvars or explicit
+     * API calls. Also refreshes ACI-7 foreground inversion via the style
+     * manager. Does not touch `COLORTHEME` / UI chrome.
+     */
+    AcTrView2d.prototype.applyCanvasBackground = function (value) {
+        this._renderer.setClearColor(value);
+        this._renderer.currentBackgroundColor = value;
+        this._renderer.changeBackground(value);
+        this.editor.syncCursorBackground(value);
+        this._isDirty = true;
+    };
+    AcTrView2d.prototype.isModelSpaceLayout = function (database) {
+        if (!database) {
+            return this.activeLayoutBtrId === this.modelSpaceBtrId;
+        }
+        return isModelSpaceDatabase(database);
+    };
+    /**
+     * Re-reads layout background sysvars from the active database. Called after
+     * a document is opened so DWG-stored values take effect.
+     */
+    AcTrView2d.prototype.syncDisplaySysVars = function (database) {
+        this.applyCanvasBackground(readLayoutBackgroundColor(database, this.isModelSpaceLayout(database)));
+    };
+    /**
+     * Re-apply canvas background after a layout tab switch using the sysvar for
+     * the newly active layout (model or paper space).
+     */
+    AcTrView2d.prototype.refreshCanvasBackgroundForActiveLayout = function () {
+        var _a, _b;
+        var docManager = AcApDocManager;
+        var database = (_b = (_a = docManager._instance) === null || _a === void 0 ? void 0 : _a.curDocument) === null || _b === void 0 ? void 0 : _b.database;
+        if (!database)
+            return;
+        var isModelSpace = this.activeLayoutBtrId === this.modelSpaceBtrId;
+        this.applyCanvasBackground(readLayoutBackgroundColor(database, isModelSpace));
+    };
     Object.defineProperty(AcTrView2d.prototype, "modelSpaceBtrId", {
         /**
          * The block table record id of the model space
@@ -526,6 +623,16 @@ var AcTrView2d = /** @class */ (function (_super) {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(AcTrView2d.prototype, "cadScene", {
+        /**
+         * CAD scene graph used for rendering and HTML export.
+         */
+        get: function () {
+            return this._scene;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(AcTrView2d.prototype, "internalScene", {
         /**
          * The internal THREE scene used by this view.
@@ -653,30 +760,248 @@ var AcTrView2d = /** @class */ (function (_super) {
         this.activeLayoutView.flyTo(point, scale);
         this._isDirty = true;
     };
+    AcTrView2d.prototype.openPickedMTextEditor = function (e) {
+        return __awaiter(this, void 0, void 0, function () {
+            var point, worldPoint, picked, entity;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        point = this.viewportToCanvas({
+                            x: e.clientX,
+                            y: e.clientY
+                        });
+                        worldPoint = this.screenToWorld(point);
+                        picked = this.pick(worldPoint, undefined, true);
+                        if (!picked.length)
+                            return [2 /*return*/];
+                        entity = AcApDocManager.instance.curDocument.database.tables.blockTable.getEntityById(picked[0].id);
+                        if (!(entity instanceof AcDbMText))
+                            return [2 /*return*/];
+                        e.preventDefault();
+                        return [4 /*yield*/, this.editMTextEntity(entity)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    AcTrView2d.prototype.editMTextEntity = function (mtext) {
+        return __awaiter(this, void 0, void 0, function () {
+            var editor, applied, result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (mtext.lineSpacingFactor !== AcEdMTextEditor.defaultLineSpacingFactor) {
+                            mtext.lineSpacingFactor = AcEdMTextEditor.defaultLineSpacingFactor;
+                            mtext.triggerModifiedEvent();
+                        }
+                        // Hide the in-scene MTEXT while the inline editor renders its own copy; otherwise
+                        // both draw at once (double text) when the user double-clicks to edit.
+                        // this.removeEntity(mtext)
+                        this._isDirty = true;
+                        editor = new AcEdMTextEditor();
+                        applied = false;
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, , 3, 4]);
+                        return [4 /*yield*/, editor.open({
+                                view: this,
+                                location: mtext.location,
+                                width: this.resolveMTextEditorWidth(mtext),
+                                textHeight: this.resolveMTextEditorTextHeight(mtext),
+                                initialText: mtext.contents,
+                                initialAttachmentPoint: mtext.attachmentPoint,
+                                toolbarFontFamilies: this.getMTextToolbarFontFamilies()
+                            })];
+                    case 2:
+                        result = _a.sent();
+                        if (!result)
+                            return [2 /*return*/];
+                        mtext.location = result.location;
+                        mtext.contents = result.contents;
+                        mtext.width = result.width;
+                        mtext.height = result.height;
+                        mtext.lineSpacingFactor = result.lineSpacingFactor;
+                        mtext.attachmentPoint = result.attachmentPoint;
+                        mtext.triggerModifiedEvent();
+                        applied = true;
+                        return [3 /*break*/, 4];
+                    case 3:
+                        if (!applied) {
+                            this.updateEntity(mtext);
+                            this._isDirty = true;
+                        }
+                        return [7 /*endfinally*/];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    AcTrView2d.prototype.resolveMTextEditorWidth = function (mtext) {
+        var width = Number(mtext.width);
+        if (Number.isFinite(width) && width > 0)
+            return width;
+        return 1e-4;
+    };
+    AcTrView2d.prototype.resolveMTextEditorTextHeight = function (mtext) {
+        var textHeight = Number(mtext.height);
+        if (Number.isFinite(textHeight) && textHeight > 0)
+            return textHeight;
+        return this.pixelsToWorldY(24);
+    };
+    AcTrView2d.prototype.pixelsToWorldY = function (pixels) {
+        var p0 = this.screenToWorld({ x: 0, y: 0 });
+        var p1 = this.screenToWorld({ x: 0, y: pixels });
+        return Math.max(Math.abs(p1.y - p0.y), 1e-4);
+    };
+    AcTrView2d.prototype.getMTextToolbarFontFamilies = function () {
+        return Array.from(new Set(AcApDocManager.instance.avaiableFonts
+            .flatMap(function (fontInfo) { return fontInfo.name; })
+            .map(function (fontName) { return fontName.trim(); })
+            .filter(function (fontName) { return fontName.length > 0; })));
+    };
     /**
      * @inheritdoc
+     *
+     * In **paper space** layouts the selection pipeline supports
+     * "drill-through": clicks inside a viewport rectangle resolve against
+     * the model-space entities that are visually rendered through that
+     * viewport, rather than picking the viewport's border. Clicks **near**
+     * the border still pick the `AcDbViewport` entity itself so the user
+     * can grip, move, lock or delete the viewport.
+     *
+     * This mirrors AutoCAD **web** behaviour (single-click selection of
+     * model content through the viewport). The desktop ARX behaviour
+     * (explicit MSPACE/PSPACE modes, CVPORT system variable, double-click
+     * to enter mspace) is a separate, larger feature — tracked in
+     * `.claude/plans/next_14_viewports_full.md` PR-γ Option A. We
+     * intentionally do **not** implement it here.
+     *
+     * The border vs interior decision uses a tolerance derived from
+     * `selectionBoxSize` (the same pixel-sized hit radius used elsewhere
+     * in pick) converted to paper-space WCS via `pointToBox`. This keeps
+     * the gesture consistent with how other entity edges behave — you
+     * don't have to land pixel-perfect on the viewport line to grab it.
      */
     AcTrView2d.prototype.pick = function (point, hitRadius, pickOneOnly) {
+        var e_1, _a;
         if (point == null)
             point = this.curPos;
         var results = [];
         var activeLayout = this._scene.activeLayout;
-        if (activeLayout) {
-            var activeLayoutView = this.activeLayoutView;
-            var box = activeLayoutView.pointToBox(point, hitRadius !== null && hitRadius !== void 0 ? hitRadius : this.selectionBoxSize);
-            var firstQueryResults = this._scene.search(box);
-            var threshold = Math.max(box.size.width / 2, box.size.height / 2);
-            var raycaster_1 = activeLayoutView.resetRaycaster(point, threshold);
-            firstQueryResults.forEach(function (item) {
-                var objectId = item.id;
-                if (activeLayout.isIntersectWith(objectId, raycaster_1)) {
+        if (!activeLayout)
+            return results;
+        var activeLayoutView = this.activeLayoutView;
+        var effectiveHitRadius = hitRadius !== null && hitRadius !== void 0 ? hitRadius : this.selectionBoxSize;
+        var paperBox = activeLayoutView.pointToBox(point, effectiveHitRadius);
+        var threshold = Math.max(paperBox.size.width / 2, paperBox.size.height / 2);
+        // Identify drill-through viewports (paper space only): viewports whose
+        // paper rectangle contains the click AND whose border is NOT within
+        // tolerance of the click. The border tolerance is the average of the
+        // hit-box width/height — a robust, scale-aware proxy for "user is
+        // trying to grab the frame, not click inside".
+        var isPaperSpace = activeLayoutView.layoutBtrId !== this._scene.modelSpaceBtrId;
+        var borderTolerance = (paperBox.size.width + paperBox.size.height) / 2;
+        var drillThroughViewports = [];
+        var drillThroughViewportIds = new Set();
+        if (isPaperSpace) {
+            try {
+                for (var _b = __values(activeLayoutView.viewportViews), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var vpView = _c.value;
+                    if (vpView.containsPaperPoint(point) &&
+                        !vpView.isNearPaperBorder(point, borderTolerance)) {
+                        drillThroughViewports.push(vpView);
+                        drillThroughViewportIds.add(vpView.viewport.id);
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        // 1) Resolve hits in the active layout. Skip the `AcDbViewport`
+        //    entity for any viewport we're drilling through — otherwise the
+        //    rectangle's bounding box always wins (it covers the whole click
+        //    region) and selection feels "stuck on the frame".
+        var firstQueryResults = this._scene.search(paperBox);
+        var raycaster = activeLayoutView.resetRaycaster(point, threshold);
+        firstQueryResults.forEach(function (item) {
+            if (drillThroughViewportIds.has(item.id))
+                return;
+            if (activeLayout.isIntersectWith(item.id, raycaster)) {
+                results.push(item);
+            }
+        });
+        // 2) For each drill-through viewport, resolve hits against the
+        //    model-space layout using the viewport's own camera/raycaster.
+        if (drillThroughViewports.length > 0) {
+            this.pickThroughViewports(point, paperBox, drillThroughViewports, results);
+        }
+        var sortedResults = sortPickResults(results, point);
+        return pickOneOnly ? sortedResults.slice(0, 1) : sortedResults;
+    };
+    /**
+     * Resolves hits against the model-space layout for each viewport the
+     * click drills through. Appends the matches into `results` (caller
+     * sorts/dedups). Kept private and separate from `pick` so the main
+     * pick path stays a single straight read.
+     *
+     * Each viewport gets its own raycaster shot (using the viewport view's
+     * own camera, which is zoomed to `viewport.viewBox` in model WCS), so
+     * a click that lands in overlapping viewports correctly resolves
+     * against each viewport's particular model framing.
+     *
+     * `pickThroughViewports` does NOT consult the active (paper) layout's
+     * spatial index — that work is already done by the caller. It only
+     * adds model-space results that would otherwise be invisible to the
+     * paper-space pick.
+     */
+    AcTrView2d.prototype.pickThroughViewports = function (paperPoint, paperBox, viewports, results) {
+        var e_2, _a;
+        var modelLayout = this._scene.modelSpaceLayout;
+        if (!modelLayout)
+            return;
+        // Half-extent of the paper-space hit box (== "radius" in paper WCS).
+        // Multiplied per viewport by its paper→model scale, this becomes a
+        // model-WCS radius that the per-viewport raycaster threshold and the
+        // spatial-index probe both use. This keeps the hit area visually
+        // consistent across viewports at different zoom levels.
+        var paperHalfRadius = (paperBox.size.width + paperBox.size.height) / 4;
+        var _loop_1 = function (vpView) {
+            var modelPt = vpView.paperPointToModel(paperPoint);
+            var modelRadius = paperHalfRadius * vpView.paperToModelScale;
+            if (modelRadius <= 0)
+                return "continue";
+            var modelBox = new AcGeBox2d().setFromPoints([
+                new AcGePoint2d(modelPt.x - modelRadius, modelPt.y - modelRadius),
+                new AcGePoint2d(modelPt.x + modelRadius, modelPt.y + modelRadius)
+            ]);
+            var vpRaycaster = vpView.resetRaycaster(modelPt, modelRadius);
+            var modelHits = modelLayout.search(modelBox);
+            modelHits.forEach(function (item) {
+                if (modelLayout.isIntersectWith(item.id, vpRaycaster)) {
                     results.push(item);
                 }
             });
-            var sortedResults = sortPickResults(results, point);
-            return pickOneOnly ? sortedResults.slice(0, 1) : sortedResults;
+        };
+        try {
+            for (var viewports_1 = __values(viewports), viewports_1_1 = viewports_1.next(); !viewports_1_1.done; viewports_1_1 = viewports_1.next()) {
+                var vpView = viewports_1_1.value;
+                _loop_1(vpView);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (viewports_1_1 && !viewports_1_1.done && (_a = viewports_1.return)) _a.call(viewports_1);
+            }
+            finally { if (e_2) throw e_2.error; }
         }
-        return results;
     };
     /**
      * @inheritdoc
@@ -851,6 +1176,91 @@ var AcTrView2d = /** @class */ (function (_super) {
         this.createLayoutViewIfNeeded(layout.blockTableRecordId);
         this._isDirty = true;
     };
+    /**
+     * Marks a layout as already framed by an external caller (typically
+     * `AcApDocManager.onAfterOpenDocument`, which zooms the startup
+     * layout right after parsing). Subsequent `layoutSwitched` events
+     * for this btrId will skip their initial zoom-to-fit so the user's
+     * camera state on the startup layout is preserved when they click
+     * back to that tab.
+     *
+     * This is the public counterpart of the `_initializedLayouts` set —
+     * exposed so the application layer can stay in sync with the view's
+     * notion of "which layouts have been framed already" without
+     * needing access to private state.
+     */
+    AcTrView2d.prototype.markLayoutAsInitialized = function (layoutBtrId) {
+        this._initializedLayouts.add(layoutBtrId);
+    };
+    /**
+     * Applies the initial zoom-to-fit for a layout the user just switched
+     * into for the first time. Picks the best available "what should the
+     * camera frame?" signal in this order:
+     *
+     * 1. **`AcDbLayout.limits`** (LIMMIN/LIMMAX) — only when it actually
+     *    contains the layout's viewports. Many real DWGs ship with garbage
+     *    limits (e.g. `(0,0)-(12,9)` from a legacy template setup) that
+     *    don't reflect the actual paper sheet. We reject those by
+     *    checking containment against `viewportsBoundingBox`.
+     *
+     * 2. **`AcTrLayoutView.viewportsBoundingBox`** — bounding box of all
+     *    real user viewports in the layout. In production sheets viewports
+     *    typically span 70-90% of the paper, so this is a great proxy for
+     *    the printable area and (crucially) ignores outliers like title
+     *    blocks authored in a different unit/scale.
+     *
+     * 3. **`AcDbLayout.extents`** — the layout's own EXTMIN/EXTMAX, if
+     *    populated. Many parsers leave this empty (we've seen `(0,0)-(0,0)`),
+     *    so it sits below the viewport-based heuristic.
+     *
+     * 4. **`zoomToFitDrawing`** (entity extents from spatial index) —
+     *    last-resort fallback for layouts with no viewports and no
+     *    sensible limits/extents (e.g. a freshly created empty paper).
+     *    Vulnerable to scale-mismatch outliers, but better than no zoom.
+     *
+     * **Critically, this runs through `AcEdConditionWaiter`**: at the
+     * moment `layoutSwitched` fires, the layout's entities (including its
+     * `AcDbViewport`s) have not yet been batch-converted into the scene
+     * — `loadLayoutEntitiesIfNeeded` chunked-converts via `setTimeout`.
+     * Without the waiter, `viewportsBoundingBox` returns undefined and
+     * the strategy degrades into (1) zooming to garbage `limits`, or
+     * (4) zooming to an empty scene box. The waiter polls
+     * `_numOfEntitiesToProcess` and only fires the heuristic once the
+     * conversion is done.
+     */
+    AcTrView2d.prototype.applyInitialZoom = function (btrId, layout) {
+        var _this = this;
+        var waiter = new AcEdConditionWaiter(function () { return _this._numOfEntitiesToProcess <= 0; }, function () {
+            var limits = layout.limits;
+            var layoutView = _this._layoutViewManager.getAt(btrId);
+            var vpsBox = layoutView === null || layoutView === void 0 ? void 0 : layoutView.viewportsBoundingBox;
+            var limitsContainsViewports = (function () {
+                if (!limits || limits.isEmpty())
+                    return false;
+                if (!vpsBox)
+                    return true;
+                return (limits.min.x <= vpsBox.min.x &&
+                    limits.min.y <= vpsBox.min.y &&
+                    limits.max.x >= vpsBox.max.x &&
+                    limits.max.y >= vpsBox.max.y);
+            })();
+            if (limits && !limits.isEmpty() && limitsContainsViewports) {
+                _this.zoomTo(limits);
+            }
+            else if (vpsBox) {
+                _this.zoomTo(vpsBox);
+            }
+            else if (layout.extents && !layout.extents.isEmpty()) {
+                var extents = layout.extents;
+                _this.zoomTo(new AcGeBox2d({ x: extents.min.x, y: extents.min.y }, { x: extents.max.x, y: extents.max.y }));
+            }
+            else if (_this._scene.box) {
+                _this.zoomTo(AcTrGeometryUtil.threeBox3dToGeBox2d(_this._scene.box));
+            }
+            _this._isDirty = true;
+        }, 300, 0);
+        waiter.start();
+    };
     /**
      * @inheritdoc
      */
@@ -938,10 +1348,26 @@ var AcTrView2d = /** @class */ (function (_super) {
     /**
      * Load entities from the specified layout if they haven't been loaded yet.
      * This ensures that when switching to a layout, all its entities are available for rendering.
+     *
+     * Two non-obvious invariants are enforced here:
+     *
+     * 1. The layout is looked up by `layoutBtrId` (the argument), not by
+     *    `this._scene.activeLayout`. The active layout reference happens to
+     *    match in the current `layoutSwitched` handler call site, but relying
+     *    on it would silently miss layouts that are pre-loaded ahead of
+     *    becoming active (e.g. background prefetch).
+     * 2. The `_loadingLayouts` guard prevents re-entrance while the
+     *    `setTimeout` chunked-convert callback is still in flight. Without it,
+     *    clicking the same layout tab twice in quick succession (or
+     *    `layoutSwitched` firing twice during the async window) would iterate
+     *    the block table record again and duplicate every entity in the
+     *    layout — visible as ghosted overdraw and double the spatial-index
+     *    weight.
+     *
      * @param layoutBtrId Input the block table record id of the layout
      */
     AcTrView2d.prototype.loadLayoutEntitiesIfNeeded = function (layoutBtrId) {
-        var e_1, _a;
+        var e_3, _a;
         var _this = this;
         try {
             var db = AcApDocManager.instance.curDocument.database;
@@ -949,10 +1375,60 @@ var AcTrView2d = /** @class */ (function (_super) {
             if (!blockTableRecord) {
                 return;
             }
-            var layout = this._scene.activeLayout;
-            if (layout && layout.isLoaded) {
+            var existingLayout = this._scene.layouts.get(layoutBtrId);
+            if (existingLayout && existingLayout.isLoaded) {
                 return;
             }
+            if (this._loadingLayouts.has(layoutBtrId)) {
+                return;
+            }
+            // Ensure `AcTrViewportView`s exist for every real `AcDbViewport`
+            // in this layout when the layout's entities were already streamed
+            // in by the document parser. There is a race in the parser-driven
+            // load path: `addLayout(layout)` creates the `AcTrLayoutView`,
+            // but the parser may dispatch the AcDbViewport entities before
+            // that happens. When that races, `batchConvert`'s viewport
+            // handler does `_layoutViewManager.getAt(entity.ownerId)`, gets
+            // `undefined`, and **silently skips creating the
+            // AcTrViewportView**. The reload path below used to mask this by
+            // re-running batchConvert after the layoutView existed, but the
+            // entityCount-skip optimization that follows removes that
+            // side-effect, so we do the viewport-view-only pass explicitly
+            // here. Skipped when the layout is empty — in that case the
+            // batchConvert path below will create the viewport views directly
+            // as it processes each entity.
+            var layoutView = this._layoutViewManager.getAt(layoutBtrId);
+            if (existingLayout &&
+                existingLayout.entityCount > 0 &&
+                layoutView &&
+                layoutView.viewportCount === 0) {
+                this.ensureViewportViews(blockTableRecord, layoutView);
+            }
+            // Model space (and any other layout pre-populated by the document
+            // parser at open time) lands here without `isLoaded` ever having
+            // been flipped — the initial entity stream goes through
+            // `addEntity()` directly, bypassing this method. Without this
+            // guard, switching back to model space from a paper layout would
+            // re-iterate the full block table record and re-batch-convert
+            // every entity (5759+ on real DWGs), freezing the UI for several
+            // seconds AND duplicating entities (every entity ends up in the
+            // layout twice, doubling the spatial-index weight and render
+            // cost).
+            //
+            // If the layout already has entities, the parser has finished
+            // loading them — flip the flag and bail. The reload path below
+            // is only for layouts whose entities were never streamed in
+            // (typically non-active paper-space layouts loaded on first user
+            // visit).
+            if (existingLayout && existingLayout.entityCount > 0) {
+                existingLayout.isLoaded = true;
+                return;
+            }
+            // Ensure layout exists in scene. `addEmptyLayout` is idempotent, but
+            // guarding the call avoids an unnecessary Map probe + log noise.
+            if (!existingLayout) {
+                this._scene.addEmptyLayout(layoutBtrId);
+            }
             // Collect all entities from this layout
             var entities_1 = [];
             var iterator = blockTableRecord.newIterator();
@@ -962,34 +1438,46 @@ var AcTrView2d = /** @class */ (function (_super) {
                     entities_1.push(entity);
                 }
             }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
             finally {
                 try {
                     if (iterator_1_1 && !iterator_1_1.done && (_a = iterator_1.return)) _a.call(iterator_1);
                 }
-                finally { if (e_1) throw e_1.error; }
+                finally { if (e_3) throw e_3.error; }
             }
-            // Ensure layout exists in scene
-            this._scene.addEmptyLayout(layoutBtrId);
-            if (entities_1.length > 0) {
-                // Load entities asynchronously
-                this._numOfEntitiesToProcess += entities_1.length;
-                setTimeout(function () { return __awaiter(_this, void 0, void 0, function () {
-                    var layout;
-                    return __generator(this, function (_a) {
-                        switch (_a.label) {
-                            case 0: return [4 /*yield*/, this.batchConvert(entities_1)];
-                            case 1:
-                                _a.sent();
-                                layout = this._scene.layouts.get(layoutBtrId);
-                                if (layout) {
-                                    layout.isLoaded = true;
-                                }
-                                return [2 /*return*/];
-                        }
-                    });
-                }); });
+            if (entities_1.length === 0) {
+                // Empty layout (e.g. a freshly-created paper space tab). Mark as
+                // loaded immediately so subsequent visits short-circuit.
+                var layout = this._scene.layouts.get(layoutBtrId);
+                if (layout) {
+                    layout.isLoaded = true;
+                }
+                return;
             }
+            // Load entities asynchronously
+            this._loadingLayouts.add(layoutBtrId);
+            this._numOfEntitiesToProcess += entities_1.length;
+            setTimeout(function () { return __awaiter(_this, void 0, void 0, function () {
+                var layout;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            _a.trys.push([0, , 2, 3]);
+                            return [4 /*yield*/, this.batchConvert(entities_1)];
+                        case 1:
+                            _a.sent();
+                            layout = this._scene.layouts.get(layoutBtrId);
+                            if (layout) {
+                                layout.isLoaded = true;
+                            }
+                            return [3 /*break*/, 3];
+                        case 2:
+                            this._loadingLayouts.delete(layoutBtrId);
+                            return [7 /*endfinally*/];
+                        case 3: return [2 /*return*/];
+                    }
+                });
+            }); });
         }
         catch (error) {
             log.error('[AcTrView2d] Error loading layout entities:', error);
@@ -1011,6 +1499,48 @@ var AcTrView2d = /** @class */ (function (_super) {
     AcTrView2d.prototype.drawEntity = function (entity, delay) {
         return entity.worldDraw(this._renderer, delay);
     };
+    /**
+     * Walks the given block table record once and creates one
+     * `AcTrViewportView` for every real `AcDbViewport` entity it finds
+     * (skipping the default paper-space viewport that is filtered
+     * everywhere else by `AcTrViewportView.isDefaultPaperSpaceViewport`).
+     *
+     * This is the recovery pass for paper-space layouts whose viewport
+     * entities reached `batchConvert` before the `AcTrLayoutView` was
+     * created — those entities were drawn and added to the scene, but
+     * the viewport-view creation step silently no-oped (lookup returned
+     * undefined). Without this recovery, `viewportsBoundingBox` stays
+     * `undefined` on first user visit, the initial-zoom strategy
+     * degrades to the bogus `limits` branch, and the layout renders as
+     * a "grain in the corner" with empty viewport scissors. See the
+     * call site in `loadLayoutEntitiesIfNeeded` for the full context.
+     *
+     * Cheap operation: only AcDbViewport entities are inspected; for a
+     * typical sheet that's a handful of entities even on 5000-entity
+     * paper layouts.
+     */
+    AcTrView2d.prototype.ensureViewportViews = function (blockTableRecord, layoutView) {
+        var e_4, _a;
+        var iterator = blockTableRecord.newIterator();
+        try {
+            for (var iterator_2 = __values(iterator), iterator_2_1 = iterator_2.next(); !iterator_2_1.done; iterator_2_1 = iterator_2.next()) {
+                var entity = iterator_2_1.value;
+                if (!(entity instanceof AcDbViewport))
+                    continue;
+                if (AcTrViewportView.isDefaultPaperSpaceViewport(entity))
+                    continue;
+                var viewportView = new AcTrViewportView(layoutView, entity.toGiViewport(), this._renderer);
+                layoutView.addViewport(viewportView);
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (iterator_2_1 && !iterator_2_1.done && (_a = iterator_2.return)) _a.call(iterator_2);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+    };
     /**
      * Converts the specified database entities to three entities
      * @param entities - The database entities
@@ -1030,6 +1560,24 @@ var AcTrView2d = /** @class */ (function (_super) {
                         _a.label = 2;
                     case 2:
                         _a.trys.push([2, 6, 7, 8]);
+                        // Skip the default paper-space viewport (`*Paper_Space`) entirely:
+                        // it is an AutoCAD-internal viewport that exists in every paper
+                        // layout and must not be drawn (would render a giant rectangle in
+                        // the paper coordinate system), nor added to the spatial index
+                        // (would stretch the layout's bounding box and break
+                        // zoomToFitDrawing), nor turned into an AcTrViewportView (would
+                        // setScissor over most of the canvas and squeeze the real user
+                        // viewports into a corner). See
+                        // `AcTrViewportView.isDefaultPaperSpaceViewport` for the criterion
+                        // and the rationale (legacy `number === 1` is unreliable across
+                        // parsers).
+                        if (entity instanceof AcDbViewport &&
+                            AcTrViewportView.isDefaultPaperSpaceViewport(entity)) {
+                            return [3 /*break*/, 8];
+                        }
+                        if (!entity.visibility) {
+                            return [3 /*break*/, 8];
+                        }
                         threeEntity = this.drawEntity(entity, true);
                         if (!threeEntity)
                             return [3 /*break*/, 8];
@@ -1059,10 +1607,12 @@ var AcTrView2d = /** @class */ (function (_super) {
                         _a.label = 5;
                     case 5:
                         if (entity instanceof AcDbViewport) {
-                            // In paper space layouts, there is always a system-defined "default" viewport that exists as
-                            // the bottom-most item. This viewport doesn't show any entities and is mainly for internal
-                            // AutoCAD purposes. The viewport id number of this system-defined "default" viewport is 1.
-                            if (entity.number !== 1) {
+                            // Default paper-space viewport was already filtered out at the
+                            // top of the loop, so anything that reaches here is a real
+                            // user-created viewport. The redundant check below is kept as
+                            // a defensive guard in case a future refactor reorders the
+                            // early-skip — it costs ~nothing and prevents a regression.
+                            if (!AcTrViewportView.isDefaultPaperSpaceViewport(entity)) {
                                 layoutView = this._layoutViewManager.getAt(entity.ownerId);
                                 if (layoutView) {
                                     viewportView = new AcTrViewportView(layoutView, entity.toGiViewport(), this._renderer);
@@ -1092,12 +1642,15 @@ var AcTrView2d = /** @class */ (function (_super) {
         });
     };
     AcTrView2d.prototype.handleGroup = function (group) {
-        var e_2, _a;
+        var e_5, _a;
         var _this = this;
         var children = group.children;
         var objectsGroupByLayer = new Map();
         children.forEach(function (child) {
             var _a;
+            if (!child.visible) {
+                return;
+            }
             var layerName = child.userData.layerName;
             if (!objectsGroupByLayer.has(layerName)) {
                 objectsGroupByLayer.set(layerName, []);
@@ -1120,12 +1673,12 @@ var AcTrView2d = /** @class */ (function (_super) {
                 child.parent = null;
             }
         }
-        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        catch (e_5_1) { e_5 = { error: e_5_1 }; }
         finally {
             try {
                 if (children_1_1 && !children_1_1.done && (_a = children_1.return)) _a.call(children_1);
             }
-            finally { if (e_2) throw e_2.error; }
+            finally { if (e_5) throw e_5.error; }
         }
         var styleManager = group.styleManager;
         var groupObjectId = group.objectId;
@@ -1180,7 +1733,7 @@ var AcTrView2d = /** @class */ (function (_super) {
      * @param effectiveLayerName - Final layer name used by rendering and style updates.
      */
     AcTrView2d.prototype.remapInheritedLayerObjects = function (objects, sourceLayerName, effectiveLayerName) {
-        var e_3, _a;
+        var e_6, _a;
         var _this = this;
         if (sourceLayerName === effectiveLayerName)
             return;
@@ -1209,12 +1762,12 @@ var AcTrView2d = /** @class */ (function (_super) {
                 });
             }
         }
-        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        catch (e_6_1) { e_6 = { error: e_6_1 }; }
         finally {
             try {
                 if (objects_1_1 && !objects_1_1.done && (_a = objects_1.return)) _a.call(objects_1);
             }
-            finally { if (e_3) throw e_3.error; }
+            finally { if (e_6) throw e_6.error; }
         }
     };
     /**