@sequent-org/moodboard 1.3.5 → 1.4.1

package/src/core/index.js

@@ -7,6 +7,7 @@ import { HistoryManager } from './HistoryManager.js';
 import { ApiClient } from './ApiClient.js';
 import { ImageUploadService } from '../services/ImageUploadService.js';
 import { FileUploadService } from '../services/FileUploadService.js';
+import { GridSnapResolver } from '../services/GridSnapResolver.js';
 import { CreateObjectCommand, DeleteObjectCommand, MoveObjectCommand, PasteObjectCommand } from './commands/index.js';
 import { Events } from './events/Events.js';
 import { generateObjectId } from '../utils/objectIdGenerator.js';
@@ -17,6 +18,10 @@ import { setupObjectLifecycleFlow } from './flows/ObjectLifecycleFlow.js';
 import { setupLayerAndViewportFlow } from './flows/LayerAndViewportFlow.js';
 import { setupRevitFlow } from './flows/RevitFlow.js';
 import { setupSaveFlow } from './flows/SaveFlow.js';
+import {
+    logMindmapCompoundDebug,
+    normalizeMindmapPropertiesForCreate,
+} from '../mindmap/MindmapCompoundContract.js';
 
 export class CoreMoodBoard {
     constructor(container, options = {}) {
@@ -60,6 +65,7 @@ export class CoreMoodBoard {
             requireCsrf: this.options.requireCsrf !== false, // По умолчанию требуем CSRF
             csrfToken: this.options.csrfToken
         });
+        this.gridSnapResolver = new GridSnapResolver(this);
         
         // Связываем SaveManager с ApiClient для правильной обработки изображений
         this.saveManager.setApiClient(this.apiClient);
@@ -212,6 +218,14 @@ export class CoreMoodBoard {
         this._historyEventsInitialized = true;
         // Следим за изменениями истории для обновления UI
         this.eventBus.on(Events.History.Changed, (data) => {
+            if (typeof data?.currentCommand === 'string' && data.currentCommand.toLowerCase().includes('mindmap')) {
+                logMindmapCompoundDebug('history:changed', {
+                    currentCommand: data.currentCommand,
+                    canUndo: !!data.canUndo,
+                    canRedo: !!data.canRedo,
+                    historySize: data.historySize,
+                });
+            }
 
             
             // Можно здесь обновить состояние кнопок Undo/Redo в UI
@@ -243,22 +257,30 @@ export class CoreMoodBoard {
      * Прямое обновление позиции объекта (без команды)
      * Используется во время перетаскивания для плавного движения
      */
-    updateObjectPositionDirect(objectId, position) {
+    updateObjectPositionDirect(objectId, position, options = {}) {
         // position — левый верх (state); приводим к центру в PIXI, используя размеры PIXI объекта
         // Все объекты используют pivot по центру, поэтому логика одинакова для всех
         const pixiObject = this.pixi.objects.get(objectId);
+        let nextPosition = position;
+        const applySnap = options.snap !== false;
+        if (applySnap && pixiObject && this.gridSnapResolver) {
+            nextPosition = this.gridSnapResolver.snapWorldTopLeft(position, {
+                width: pixiObject.width || 0,
+                height: pixiObject.height || 0,
+            });
+        }
         if (pixiObject) {
             const halfW = (pixiObject.width || 0) / 2;
             const halfH = (pixiObject.height || 0) / 2;
-            pixiObject.x = position.x + halfW;
-            pixiObject.y = position.y + halfH;
+            pixiObject.x = nextPosition.x + halfW;
+            pixiObject.y = nextPosition.y + halfH;
         }
         
         // Обновляем позицию в состоянии (без эмита события)
         const objects = this.state.state.objects;
         const object = objects.find(obj => obj.id === objectId);
         if (object) {
-            object.position = { ...position };
+            object.position = { ...nextPosition };
             this.state.markDirty(); // Помечаем для автосохранения
         }
     }
@@ -282,7 +304,7 @@ export class CoreMoodBoard {
      * Прямое обновление размера и позиции объекта (без команды)
      * Используется во время изменения размера для плавного изменения
      */
-    updateObjectSizeAndPositionDirect(objectId, size, position = null, objectType = null) {
+    updateObjectSizeAndPositionDirect(objectId, size, position = null, objectType = null, options = {}) {
         // Обновляем размер в PIXI
         const pixiObject = this.pixi.objects.get(objectId);
         const prevCenter = pixiObject ? { x: pixiObject.x, y: pixiObject.y } : null;
@@ -290,19 +312,23 @@ export class CoreMoodBoard {
 
         // Обновляем позицию если передана (state: левый-верх; PIXI: центр)
         if (position) {
+            const applySnap = options.snap !== false;
+            const snappedPosition = (applySnap && this.gridSnapResolver)
+                ? this.gridSnapResolver.snapWorldTopLeft(position, size)
+                : position;
             const pixiObject2 = this.pixi.objects.get(objectId);
             if (pixiObject2) {
                 const halfW = (size?.width ?? pixiObject2.width ?? 0) / 2;
                 const halfH = (size?.height ?? pixiObject2.height ?? 0) / 2;
-                pixiObject2.x = position.x + halfW;
-                pixiObject2.y = position.y + halfH;
+                pixiObject2.x = snappedPosition.x + halfW;
+                pixiObject2.y = snappedPosition.y + halfH;
 
                 // Обновляем позицию в состоянии
                 const objects = this.state.state.objects;
                 const object = objects.find(obj => obj.id === objectId);
                 if (object) {
-                    object.position.x = position.x;
-                    object.position.y = position.y;
+                    object.position.x = snappedPosition.x;
+                    object.position.y = snappedPosition.y;
                 }
             }
         } else if (prevCenter) {
@@ -373,19 +399,44 @@ export class CoreMoodBoard {
                 properties = { ...(properties || {}), title: 'Фрейм 1' };
             }
         }
+        const snappedCreatePos = this.gridSnapResolver
+            ? this.gridSnapResolver.snapWorldTopLeft(position, {
+                width: initialWidth,
+                height: initialHeight,
+            })
+            : position;
         const objectData = {
             id: generateObjectId(exists),
             type,
-            position,
+            position: snappedCreatePos,
             width: initialWidth,
             height: initialHeight,
-            properties,
+            properties: normalizeMindmapPropertiesForCreate({
+                type,
+                objectId: null,
+                properties,
+                existingObjects: this.state?.state?.objects || [],
+            }),
             created: new Date().toISOString(),
             transform: {
                 pivotCompensated: false  // Новые объекты еще не скомпенсированы
             },
             ...extraData  // Добавляем дополнительные данные (например, imageId)
         };
+        objectData.properties = normalizeMindmapPropertiesForCreate({
+            type,
+            objectId: objectData.id,
+            properties: objectData.properties,
+            existingObjects: this.state?.state?.objects || [],
+        });
+        if (type === 'mindmap') {
+            logMindmapCompoundDebug('core:create-object', {
+                id: objectData.id,
+                role: objectData.properties?.mindmap?.role || null,
+                compoundId: objectData.properties?.mindmap?.compoundId || null,
+                parentId: objectData.properties?.mindmap?.parentId || null,
+            });
+        }
 
         // Создаем и выполняем команду создания объекта
         const command = new CreateObjectCommand(this, objectData);
@@ -440,6 +491,20 @@ export class CoreMoodBoard {
         if (objectData.transform.pivotCompensated === undefined) {
             objectData.transform.pivotCompensated = false;
         }
+        objectData.properties = normalizeMindmapPropertiesForCreate({
+            type: objectData.type,
+            objectId: objectData.id || null,
+            properties: objectData.properties || {},
+            existingObjects: this.state?.state?.objects || [],
+        });
+        if (objectData.type === 'mindmap') {
+            logMindmapCompoundDebug('core:load-object', {
+                id: objectData.id,
+                role: objectData.properties?.mindmap?.role || null,
+                compoundId: objectData.properties?.mindmap?.compoundId || null,
+                parentId: objectData.properties?.mindmap?.parentId || null,
+            });
+        }
 
         // Используем существующие данные объекта (с его ID, размерами и т.д.)
         this.state.addObject(objectData);
@@ -618,6 +683,11 @@ export class CoreMoodBoard {
             this.frameService.detach();
             this.frameService = null;
         }
+
+        if (this.boardService) {
+            this.boardService.destroy?.();
+            this.boardService = null;
+        }
         
         if (this.pixi) {
             this.pixi.destroy();

package/src/core/rendering/ObjectRenderer.js

@@ -83,8 +83,9 @@ export class ObjectRenderer {
             pixiObject.anchor.set(0.5, 0.5);
         } else if (pixiObject instanceof PIXI.Graphics) {
             const bounds = pixiObject.getBounds();
-            const pivotX = bounds.width / 2;
-            const pivotY = bounds.height / 2;
+            const isMindmap = objectData?.type === 'mindmap';
+            const pivotX = isMindmap ? Math.floor(bounds.width / 2) : (bounds.width / 2);
+            const pivotY = isMindmap ? Math.floor(bounds.height / 2) : (bounds.height / 2);
             pixiObject.pivot.set(pivotX, pivotY);
             
             // Компенсируем смещение pivot
@@ -92,6 +93,10 @@ export class ObjectRenderer {
             if (needsCompensation) {
                 pixiObject.x += pivotX;
                 pixiObject.y += pivotY;
+                if (isMindmap) {
+                    pixiObject.x = Math.round(pixiObject.x);
+                    pixiObject.y = Math.round(pixiObject.y);
+                }
             }
         }
         

package/src/grid/BaseGrid.js

@@ -1,4 +1,11 @@
 import * as PIXI from 'pixi.js';
+import {
+    DEFAULT_PHASES,
+    getScreenAnchor,
+    resolveScreenGridState,
+    snapScreenValue,
+} from './ScreenGridPhaseMachine.js';
+import { incrementGridDiagnosticCounter, logGridDiagnostic } from './GridDiagnostics.js';
 
 /**
  * Базовый класс для всех типов сеток
@@ -19,6 +26,16 @@ export class BaseGrid {
         this.height = options.height || 1080;
         /** @type {{ left: number, top: number, right: number, bottom: number } | null} */
         this.viewportBounds = null;
+        this.viewportTransform = {
+            worldX: 0,
+            worldY: 0,
+            scale: 1,
+            viewWidth: this.width,
+            viewHeight: this.height,
+        };
+        this._zoom = 1;
+        this.minScreenSpacing = options.minScreenSpacing ?? 8;
+        this.screenPhases = options.screenPhases || DEFAULT_PHASES;
         
         // PIXI графика
         this.graphics = new PIXI.Graphics();
@@ -62,6 +79,34 @@ export class BaseGrid {
         
         return this.calculateSnapPoint(x, y);
     }
+
+    /**
+     * Привязывает world-координаты к screen-grid контракту.
+     */
+    snapWorldPoint(x, y) {
+        incrementGridDiagnosticCounter('baseGrid.snapWorldPoint.calls');
+        const t = this.viewportTransform || { worldX: 0, worldY: 0, scale: 1 };
+        const scale = Math.max(0.001, t.scale || 1);
+        const screenX = (x * scale) + (t.worldX || 0);
+        const screenY = (y * scale) + (t.worldY || 0);
+        const { screenStep } = this.getScreenGridState();
+        const anchorX = getScreenAnchor(t.worldX || 0, screenStep);
+        const anchorY = getScreenAnchor(t.worldY || 0, screenStep);
+        const snappedScreenX = snapScreenValue(screenX, anchorX, screenStep);
+        const snappedScreenY = snapScreenValue(screenY, anchorY, screenStep);
+        const snapped = {
+            x: (snappedScreenX - (t.worldX || 0)) / scale,
+            y: (snappedScreenY - (t.worldY || 0)) / scale,
+        };
+        logGridDiagnostic('BaseGrid', 'snapWorldPoint', {
+            type: this.type,
+            scale,
+            screenStep,
+            input: { x, y },
+            output: snapped,
+        });
+        return snapped;
+    }
     
     /**
      * Вычисляет точку привязки к сетке
@@ -112,6 +157,10 @@ export class BaseGrid {
         this.size = Math.max(1, size);
         this.updateVisual();
     }
+
+    setZoom(scale) {
+        this._zoom = Math.max(0.01, Math.min(5, scale || 1));
+    }
     
     /**
      * Устанавливает цвет сетки
@@ -135,10 +184,19 @@ export class BaseGrid {
     resize(width, height) {
         this.width = width;
         this.height = height;
+        this.viewportTransform.viewWidth = width;
+        this.viewportTransform.viewHeight = height;
         this.viewportBounds = null;
         this.updateVisual();
     }
 
+    setViewportTransform(transform = {}) {
+        this.viewportTransform = {
+            ...this.viewportTransform,
+            ...transform,
+        };
+    }
+
     /**
      * Устанавливает видимую область для непрерывной отрисовки при паннинге.
      * @param {number} left
@@ -161,6 +219,13 @@ export class BaseGrid {
         }
         return { left: 0, top: 0, right: this.width, bottom: this.height };
     }
+
+    getScreenGridState() {
+        return resolveScreenGridState(this._zoom, {
+            minScreenSpacing: this.minScreenSpacing,
+            phases: this.screenPhases,
+        });
+    }
     
     /**
      * Возвращает PIXI объект для рендеринга

package/src/grid/CrossGrid.js

@@ -1,5 +1,6 @@
-import * as PIXI from 'pixi.js';
 import { BaseGrid } from './BaseGrid.js';
+import { getScreenAnchor } from './ScreenGridPhaseMachine.js';
+import { getCrossCheckpointForZoom, getCrossColor } from './CrossGridZoomPhases.js';
 
 /**
  * Сетка с крестиками (плюсами) в узлах
@@ -11,12 +12,23 @@ export class CrossGrid extends BaseGrid {
 
         // Размер половины креста от центра до конца линии
         this.crossHalfSize = options.crossHalfSize || 4;
-        this.crossLineWidth = options.crossLineWidth || this.lineWidth || 1;
+        this.crossLineWidth = 1;
 
         // По умолчанию делаем цвет крестиков серым
         if (options.color == null) {
             this.color = 0xB0B0B0;
         }
+        // CrossGrid всегда непрозрачный, независимо от входящих настроек.
+        this.opacity = 1;
+        this.graphics.alpha = 1;
+
+        // Cursor-centric anchor-контракт: при зуме узел под курсором фиксируется.
+        this._anchorX = null;
+        this._anchorY = null;
+        this._lastStepPxX = null;
+        this._lastStepPxY = null;
+        this._cursorOffsetX = 0;
+        this._cursorOffsetY = 0;
     }
 
     /**
@@ -24,31 +36,74 @@ export class CrossGrid extends BaseGrid {
      */
     createVisual() {
         const g = this.graphics;
-        // Прозрачность — через alpha графики (как у линейной сетки)
-        g.alpha = this.opacity;
-        // Тонкие чёткие линии как у линейной сетки: alignment = 0.5
-        try {
-            g.lineStyle({ width: Math.max(0.5, this.crossLineWidth), color: this.color, alpha: 1, alignment: 0.5 });
-        } catch (_) {
-            g.lineStyle(Math.max(0.5, this.crossLineWidth), this.color, 1);
-        }
+        // Строго без прозрачности.
+        g.alpha = 1;
+        const lineColor = getCrossColor(this._zoom, this.color);
+        g.beginFill(lineColor, 1);
 
-        const hs = this.crossHalfSize;
+        const checkpoint = getCrossCheckpointForZoom(this._zoom);
+        const hs = Math.max(1, Math.round(checkpoint.crossHalfSize || this.crossHalfSize || 1));
         const b = this.getDrawBounds();
-        const startX = Math.floor(b.left / this.size) * this.size;
-        const startY = Math.floor(b.top / this.size) * this.size;
-        const endX = Math.ceil(b.right / this.size) * this.size;
-        const endY = Math.ceil(b.bottom / this.size) * this.size;
-        for (let x = startX; x <= endX; x += this.size) {
-            for (let y = startY; y <= endY; y += this.size) {
-                const px = Math.round(x) + 0.5;
-                const py = Math.round(y) + 0.5;
-                g.moveTo(px - hs, py);
-                g.lineTo(px + hs, py);
-                g.moveTo(px, py - hs);
-                g.lineTo(px, py + hs);
+        const step = Math.max(1, Math.round(checkpoint.spacing || 20));
+        const worldX = this.viewportTransform?.worldX || 0;
+        const worldY = this.viewportTransform?.worldY || 0;
+        const cursorX = this.viewportTransform?.zoomCursorX;
+        const cursorY = this.viewportTransform?.zoomCursorY;
+        const useCursorAnchor = this.viewportTransform?.useCursorAnchor === true;
+        const anchorX = this._resolveScreenAnchor('x', worldX, step, cursorX, useCursorAnchor);
+        const anchorY = this._resolveScreenAnchor('y', worldY, step, cursorY, useCursorAnchor);
+        const alignStart = (min, anchor) => {
+            const d = ((anchor - min) % step + step) % step;
+            return min + d;
+        };
+        const startX = alignStart(b.left, anchorX);
+        const startY = alignStart(b.top, anchorY);
+        const endX = b.right + step;
+        const endY = b.bottom + step;
+        for (let x = startX; x <= endX; x += step) {
+            for (let y = startY; y <= endY; y += step) {
+                const px = Math.round(x);
+                const py = Math.round(y);
+                const ray = hs * 2 + 1;
+                // Строгий 1px-контракт: рисуем пиксельные прямоугольники вместо stroke-линий.
+                g.drawRect(px - hs, py, ray, 1);
+                g.drawRect(px, py - hs, 1, ray);
             }
+
         }
+        g.endFill();
+    }
+
+    _normalizeAnchor(anchor, stepPx) {
+        const step = Math.max(1, Math.round(stepPx));
+        return ((Math.round(anchor) % step) + step) % step;
+    }
+
+    _resolveScreenAnchor(axis, worldOffset, stepPx, cursorPx, useCursorAnchor) {
+        const anchorKey = axis === 'x' ? '_anchorX' : '_anchorY';
+        const lastStepKey = axis === 'x' ? '_lastStepPxX' : '_lastStepPxY';
+        const cursorOffsetKey = axis === 'x' ? '_cursorOffsetX' : '_cursorOffsetY';
+        const step = Math.max(1, Math.round(stepPx));
+        const rawAnchor = this._normalizeAnchor(getScreenAnchor(worldOffset, step), step);
+
+        if (useCursorAnchor && Number.isFinite(cursorPx)) {
+            const prevAnchor = Number(this[anchorKey]);
+            const prevStep = Math.max(1, Math.round(Number(this[lastStepKey]) || step));
+            if (Number.isFinite(prevAnchor)) {
+                this[cursorOffsetKey] = this._normalizeAnchor(Math.round(cursorPx) - prevAnchor, prevStep);
+            } else if (!Number.isFinite(this[cursorOffsetKey])) {
+                this[cursorOffsetKey] = 0;
+            }
+            const offset = this._normalizeAnchor(this[cursorOffsetKey], step);
+            const cursorAnchor = this._normalizeAnchor(Math.round(cursorPx) - offset, step);
+            this[anchorKey] = cursorAnchor;
+            this[lastStepKey] = step;
+            return cursorAnchor;
+        }
+
+        this[anchorKey] = rawAnchor;
+        this[lastStepKey] = step;
+        return rawAnchor;
     }
 
     /**
@@ -69,7 +124,17 @@ export class CrossGrid extends BaseGrid {
     }
 
     setCrossLineWidth(w) {
-        this.crossLineWidth = Math.max(1, w);
+        void w;
+        this.crossLineWidth = 1;
+        this.updateVisual();
+    }
+
+    /**
+     * CrossGrid всегда непрозрачный: внешний setOpacity игнорируется.
+     */
+    setOpacity() {
+        this.opacity = 1;
+        this.graphics.alpha = 1;
         this.updateVisual();
     }
 

package/src/grid/CrossGridZoomPhases.js

@@ -0,0 +1,167 @@
+/**
+ * Дискретный профиль cross-grid по zoom checkpoint'ам.
+ * Возвращает фиксированные screen-space параметры:
+ * - spacing: расстояние между крестами в px
+ * - crossHalfSize: половина длины креста в px
+ * - color: цвет креста (без автозатемнения)
+ */
+
+function clampZoom(zoom) {
+    return Math.max(0.01, Math.min(5, zoom || 1));
+}
+
+/**
+ * В таблице используются zoom в процентах (1 = 100%).
+ * Для дублей лейблов (8, 5, 4, 3, 2) используются существующие
+ * "двойные проходы" из low-zoom checkpoint'ов проекта.
+ */
+export const CROSS_CHECKPOINTS = [
+    { zoomPercent: 400, crossHalfSize: 8, spacing: 100 },
+    { zoomPercent: 357, crossHalfSize: 8, spacing: 90 },
+    { zoomPercent: 319, crossHalfSize: 8, spacing: 85 },
+    { zoomPercent: 285, crossHalfSize: 8, spacing: 80 },
+    { zoomPercent: 254, crossHalfSize: 8, spacing: 75 },
+    { zoomPercent: 227, crossHalfSize: 8, spacing: 70 },
+    { zoomPercent: 203, crossHalfSize: 6, spacing: 65 },
+    { zoomPercent: 181, crossHalfSize: 6, spacing: 60 },
+    { zoomPercent: 162, crossHalfSize: 6, spacing: 58 },
+    { zoomPercent: 144, crossHalfSize: 6, spacing: 56 },
+    { zoomPercent: 129, crossHalfSize: 6, spacing: 54 },
+    { zoomPercent: 115, crossHalfSize: 6, spacing: 52 },
+    { zoomPercent: 103, crossHalfSize: 4, spacing: 50 },
+    { zoomPercent: 82, crossHalfSize: 4, spacing: 48 },
+    { zoomPercent: 73, crossHalfSize: 4, spacing: 46 },
+    { zoomPercent: 65, crossHalfSize: 4, spacing: 42 },
+    { zoomPercent: 58, crossHalfSize: 4, spacing: 40 },
+    { zoomPercent: 52, crossHalfSize: 4, spacing: 38 },
+    { zoomPercent: 46, crossHalfSize: 4, spacing: 36 },
+    { zoomPercent: 41, crossHalfSize: 4, spacing: 34 },
+    { zoomPercent: 37, crossHalfSize: 4, spacing: 32 },
+    { zoomPercent: 33, crossHalfSize: 4, spacing: 30 },
+    { zoomPercent: 30, crossHalfSize: 4, spacing: 28 },
+    { zoomPercent: 26, crossHalfSize: 3, spacing: 26 },
+    { zoomPercent: 24, crossHalfSize: 3, spacing: 24 },
+    { zoomPercent: 21, crossHalfSize: 3, spacing: 22 },
+    { zoomPercent: 19, crossHalfSize: 3, spacing: 20 },
+    { zoomPercent: 17, crossHalfSize: 3, spacing: 18 },
+    { zoomPercent: 15, crossHalfSize: 3, spacing: 16 },
+    { zoomPercent: 13, crossHalfSize: 2, spacing: 14 },
+    { zoomPercent: 12, crossHalfSize: 2, spacing: 12 },
+    { zoomPercent: 11, crossHalfSize: 3, spacing: 28 },
+    { zoomPercent: 10, crossHalfSize: 3, spacing: 26 },
+    { zoomPercent: 8.4, crossHalfSize: 3, spacing: 24 },
+    { zoomPercent: 7.6, crossHalfSize: 3, spacing: 22 },
+    { zoomPercent: 7.0, crossHalfSize: 3, spacing: 20 },
+    { zoomPercent: 6.0, crossHalfSize: 3, spacing: 18 },
+    { zoomPercent: 5.4, crossHalfSize: 3, spacing: 16 },
+    { zoomPercent: 4.6, crossHalfSize: 2, spacing: 14 },
+    { zoomPercent: 4.0, crossHalfSize: 2, spacing: 12 },
+    { zoomPercent: 3.6, crossHalfSize: 3, spacing: 28 },
+    { zoomPercent: 3.4, crossHalfSize: 3, spacing: 26 },
+    { zoomPercent: 3.0, crossHalfSize: 3, spacing: 24 },
+    { zoomPercent: 2.6, crossHalfSize: 3, spacing: 22 },
+    { zoomPercent: 2.4, crossHalfSize: 3, spacing: 20 },
+    { zoomPercent: 2.2, crossHalfSize: 3, spacing: 18 },
+    { zoomPercent: 2.0, crossHalfSize: 3, spacing: 16 },
+    { zoomPercent: 1.8, crossHalfSize: 2, spacing: 14 },
+    { zoomPercent: 1.6, crossHalfSize: 2, spacing: 12 },
+    { zoomPercent: 1.4, crossHalfSize: 2, spacing: 10 },
+];
+
+function sanitizeInt(value, fallback) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return fallback;
+    return Math.max(1, Math.round(n));
+}
+
+function sanitizeColor(value, fallback = 0xB0B0B0) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return fallback;
+    return Math.max(0, Math.min(0xFFFFFF, Math.round(n)));
+}
+
+const DEFAULT_CROSS_COLOR = 0xC2C2C2;       // 194,194,194
+const DEFAULT_MID_CROSS_COLOR = 0xA7A7A7;   // 167,167,167
+const DEFAULT_SMALL_CROSS_COLOR = 0xCDCDCD; // 205,205,205
+const COLOR_BAND_HIGH = 'high';
+const COLOR_BAND_MID = 'mid';
+const COLOR_BAND_SMALL = 'small';
+
+const CROSS_COLOR_BANDS = {
+    [COLOR_BAND_HIGH]: DEFAULT_CROSS_COLOR,         // большой зум / крупная сетка
+    [COLOR_BAND_MID]: DEFAULT_MID_CROSS_COLOR,      // средний участок
+    [COLOR_BAND_SMALL]: DEFAULT_SMALL_CROSS_COLOR,  // малая сетка
+};
+
+function resolveCrossCheckpoint(zoom) {
+    const z = clampZoom(zoom);
+    const p = z * 100;
+    let best = CROSS_CHECKPOINTS[0];
+    let bestDist = Math.abs(best.zoomPercent - p);
+    for (let i = 1; i < CROSS_CHECKPOINTS.length; i += 1) {
+        const row = CROSS_CHECKPOINTS[i];
+        const dist = Math.abs(row.zoomPercent - p);
+        if (dist < bestDist) {
+            best = row;
+            bestDist = dist;
+        }
+    }
+    return best;
+}
+
+export function getCrossCheckpointForZoom(zoom) {
+    const row = resolveCrossCheckpoint(zoom);
+    const spacing = sanitizeInt(row.spacing, 20);
+    const band = resolveColorBandBySpacing(spacing);
+    return {
+        zoomPercent: row.zoomPercent,
+        crossHalfSize: sanitizeInt(row.crossHalfSize, 4),
+        spacing,
+        color: sanitizeColor(CROSS_COLOR_BANDS[band], DEFAULT_CROSS_COLOR),
+    };
+}
+
+export function getCrossScreenSpacing(zoom) {
+    return getCrossCheckpointForZoom(zoom).spacing;
+}
+
+export function getCrossHalfSize(zoom) {
+    return getCrossCheckpointForZoom(zoom).crossHalfSize;
+}
+
+function resolveColorBandBySpacing(spacing) {
+    const s = sanitizeInt(spacing, 20);
+    if (s >= 52) return COLOR_BAND_HIGH;
+    if (s >= 30) return COLOR_BAND_MID;
+    return COLOR_BAND_SMALL;
+}
+
+export function getCrossColor(zoom, fallbackColor = DEFAULT_CROSS_COLOR) {
+    const checkpoint = getCrossCheckpointForZoom(zoom);
+    const band = resolveColorBandBySpacing(checkpoint.spacing);
+    return sanitizeColor(CROSS_COLOR_BANDS[band], fallbackColor);
+}
+
+export function updateCrossCheckpoint(zoomPercent, patch = {}) {
+    const target = Number(zoomPercent);
+    if (!Number.isFinite(target)) return null;
+    const row = CROSS_CHECKPOINTS.find((r) => Math.abs(r.zoomPercent - target) < 1e-6);
+    if (!row) return null;
+    if (Object.prototype.hasOwnProperty.call(patch, 'crossHalfSize')) {
+        row.crossHalfSize = sanitizeInt(patch.crossHalfSize, row.crossHalfSize);
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'spacing')) {
+        row.spacing = sanitizeInt(patch.spacing, row.spacing);
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'color')) {
+        const band = resolveColorBandBySpacing(row.spacing);
+        CROSS_COLOR_BANDS[band] = sanitizeColor(patch.color, CROSS_COLOR_BANDS[band] ?? DEFAULT_CROSS_COLOR);
+    }
+    const band = resolveColorBandBySpacing(row.spacing);
+    return {
+        zoomPercent: row.zoomPercent,
+        crossHalfSize: sanitizeInt(row.crossHalfSize, 4),
+        spacing: sanitizeInt(row.spacing, 20),
+        color: sanitizeColor(CROSS_COLOR_BANDS[band], DEFAULT_CROSS_COLOR),
+    };
+}