@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.42

package/dist/rack-grid.js

@@ -1,200 +1,82 @@
+import { __decorate } from "tslib";
 /*
  * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * RackGrid — *grid layout 의 컨테이너*.
+ *
+ * 각 (col, row) 위치마다 *하나의 자식 컴포넌트* 보유 가능:
+ *   - StorageRack (한 column 의 vertical stack — stock 보관)
+ *   - Crane / AGV / forklift / 미니로드 등 *operation archetype* (이동/작업 설비)
+ *   - 또는 비어 있음 (= 통로 / 작업자 공간 / 무엇이든)
+ *
+ * 외부에는 *location string* (예: "Z-A01-03-1") 으로 API 노출. 내부 cellId 와 양방향
+ * 변환은 RackGrid 가 책임.
+ *
+ * **Performance** — 각 자식 StorageRack 이 자체 InstancedMesh 로 stock 렌더링.
+ *   storage-rack 의 batched 시각화 성능 그대로 계승. RackGrid 는 *얇은 wrapper*.
+ *
+ * **Transfer 컨트랙** — SlottedHolder 인터페이스 구현. 내부적으로 *자식 StorageRack*
+ *   으로 위임. Mover / Crane 등이 *RackGrid 의 slot target* 으로 인터랙트 가능.
+ *
+ * **Configuration 생산성** — rack-table 의 *location 룰* (locPattern, sectionDigits 등)
+ *   차용. cell-component 없이 *sparse cellOverrides* 만으로 동일 UX 제공.
+ *
+ * **Aisle/Empty** — `cellOverrides[posKey].isEmpty = true` 로 명시. 의미는
+ *   *location 미부여 + increaseLocation 의 aisle row 인식* 만. 그 위치의 자식 컴포넌트
+ *   종류는 *자유* (Crane/AGV/forklift/그냥 비움 모두 가능).
+ *
+ * **CellId 컨벤션** (내부):
+ *   - posKey = `${col-1}-${row-1}` (0-based, 2 segments) — *grid 평면 위치*
+ *   - cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments) — *grid + shelf*
+ *   - 자식 StorageRack 내부에서는 `0-0-${shelf-1}` (자체 cellId 형식). RackGrid 가 변환.
  */
-import { __decorate } from "tslib";
-import { Component, ContainerAbstract, Layout, Model, sceneComponent } from '@hatiolab/things-scene';
+import { ContainerAbstract, Layout, Model, sceneComponent } from '@hatiolab/things-scene';
+import * as THREE from 'three';
+import { Placeable, SlotTarget } from '@operato/scene-base';
 import { RackGrid3D } from './rack-grid-3d.js';
-import { increaseLocation } from './rack-grid-location.js';
-const NATURE = {
-    mutable: false,
-    resizable: true,
-    rotatable: true,
-    properties: [
-        {
-            type: 'number',
-            label: 'rows',
-            name: 'rows',
-            property: 'rows'
-        },
-        {
-            type: 'number',
-            label: 'columns',
-            name: 'columns',
-            property: 'columns'
-        },
-        {
-            type: 'string',
-            label: 'zone',
-            name: 'zone',
-            property: 'zone'
-        },
-        {
-            type: 'number',
-            label: 'shelves',
-            name: 'shelves',
-            property: 'shelves'
-        },
-        {
-            type: 'number',
-            label: 'depth',
-            name: 'depth',
-            property: 'depth'
-        },
-        {
-            type: 'string',
-            label: 'location-pattern',
-            name: 'locPattern',
-            placeholder: '{z}{s}-{u}-{sh}'
-        },
-        {
-            type: 'number',
-            label: 'section-digits',
-            name: 'sectionDigits',
-            placeholder: '1, 2, 3, ...'
-        },
-        {
-            type: 'number',
-            label: 'unit-digits',
-            name: 'unitDigits',
-            placeholder: '1, 2, 3, ...'
-        },
-        {
-            type: 'string',
-            label: 'shelf-locations',
-            name: 'shelfLocations',
-            placeholder: '1,2,3,... / ,,,04'
-        },
-        {
-            type: 'number',
-            label: 'stock-scale',
-            name: 'stockScale',
-            property: {
-                step: 0.01,
-                min: 0,
-                max: 1
-            }
-        },
-        {
-            type: 'checkbox',
-            label: 'hide-rack-frame',
-            name: 'hideRackFrame'
-        },
-        {
-            type: 'id-input',
-            label: 'legend-target',
-            name: 'legendTarget',
-            property: {
-                component: 'legend'
-            }
-        },
-        {
-            type: 'checkbox',
-            label: 'hide-empty-stock',
-            name: 'hideEmptyStock'
-        }
-    ],
-    help: 'scene/component/rack-grid'
-};
-const SIDES = {
-    all: ['top', 'left', 'bottom', 'right'],
-    out: ['top', 'left', 'bottom', 'right'],
-    left: ['left'],
-    right: ['right'],
-    top: ['top'],
-    bottom: ['bottom'],
-    leftright: ['left', 'right'],
-    topbottom: ['top', 'bottom']
-};
-const CLEAR_STYLE = {
-    strokeStyle: '',
-    lineDash: 'solid',
-    lineWidth: 0
-};
-const DEFAULT_STYLE = {
-    strokeStyle: '#999',
-    lineDash: 'solid',
-    lineWidth: 1
-};
-const TABLE_LAYOUT = Layout.get('table');
+// RackGridCell 의 refid 충돌 회피 — load 시 동적 생성되는 cell 의 refid 가 *부모
+// RackGrid + 모델 안 다른 컴포넌트* refid 와 겹치지 않도록 *높은 시작값 + monotonic
+// counter*. hierarchy override 가 save 시 refid 제거 → 모델 파일엔 안 새겨짐.
+let _cellRefidCounter = 100_000_000;
+function _nextCellRefid() {
+    return _cellRefidCounter++;
+}
 function buildNewCell(app) {
-    return Model.compile({
+    const refid = _nextCellRefid();
+    const m = Model.compile({
         type: 'rack-grid-cell',
-        strokeStyle: 'black',
-        fillStyle: 'transparent',
-        left: 0,
-        top: 0,
-        width: 1,
-        height: 1,
-        textWrap: true,
-        isEmpty: false,
-        border: buildBorderStyle(DEFAULT_STYLE, 'all')
+        refid,
+        left: 0, top: 0, width: 1, height: 1, isEmpty: false
     }, app);
-}
-function buildCopiedCell(copy, app) {
-    const obj = JSON.parse(JSON.stringify(copy));
-    delete obj.text;
-    return Model.compile(obj, app);
-}
-function buildBorderStyle(style, where) {
-    return (SIDES[where] || []).reduce((border, side) => {
-        border[side] = style;
-        return border;
-    }, {});
-}
-function setCellBorder(cell, style, where) {
-    if (!cell) {
-        return;
+    // Model.compile 이 refid 를 자동 generator 로 덮어쓸 수 있어 *강제 재 set*.
+    try {
+        if (m.refid !== refid) {
+            m.refid = refid;
+            m.state && (m.state.refid = refid);
+            m._state && (m._state.refid = refid);
+        }
     }
-    cell.set('border', Object.assign({}, cell.getState('border') || {}, buildBorderStyle(style, where)));
-}
-function isLeftMost(total, columns, indices, i) {
-    return i == 0 || !(i % columns) || indices.indexOf(i - 1) == -1;
-}
-function isRightMost(total, columns, indices, i) {
-    return i == total - 1 || i % columns == columns - 1 || indices.indexOf(i + 1) == -1;
-}
-function isTopMost(total, columns, indices, i) {
-    return i < columns || indices.indexOf(i - columns) == -1;
-}
-function isBottomMost(total, columns, indices, i) {
-    return i > total - columns - 1 || indices.indexOf(i + columns) == -1;
+    catch { }
+    return m;
 }
-function above(columns, i) {
-    return i - columns;
-}
-function below(columns, i) {
-    return i + columns;
-}
-function before(columns, i) {
-    return !(i % columns) ? -1 : i - 1;
-}
-function after(columns, i) {
-    return !((i + 1) % columns) ? -1 : i + 1;
-}
-function array(value, size) {
+const TABLE_LAYOUT = Layout.get('table');
+function arrayOf(value, size) {
     const arr = [];
     for (let i = 0; i < size; i++)
-        arr.push(1);
+        arr.push(value);
     return arr;
 }
 const columnControlHandler = {
-    ondragmove: function (point, index, component) {
+    ondragmove(point, index, component) {
         const { left, top, width, height } = component.textBounds;
         const widths_sum = component.widths_sum;
         const widths = component.widths.slice();
-        /* 컨트롤의 원래 위치를 구한다. */
-        const origin_pos_unit = widths.slice(0, index + 1).reduce((sum, width) => sum + width, 0);
+        const origin_pos_unit = widths.slice(0, index + 1).reduce((sum, w) => sum + w, 0);
         const origin_offset = left + (origin_pos_unit / widths_sum) * width;
-        /*
-         * point의 좌표는 부모 레이어 기준의 x, y 값이다.
-         * 따라서, 도형의 회전을 감안한 좌표로의 변환이 필요하다.
-         * Transcoord시에는 point좌표가 부모까지 transcoord되어있는 상태이므로,
-         * 컴포넌트자신에 대한 transcoord만 필요하다.(마지막 파라미터를 false로).
-         */
         const transcoorded = component.transcoordP2S(point.x, point.y);
         const diff = transcoorded.x - origin_offset;
         let diff_unit = (diff / width) * widths_sum;
-        const min_width_unit = (widths_sum / width) * 5; // 5픽셀정도를 최소로
+        const min_width_unit = (widths_sum / width) * 5;
         if (diff_unit < 0)
             diff_unit = -Math.min(widths[index] - min_width_unit, -diff_unit);
         else
@@ -205,24 +87,17 @@ const columnControlHandler = {
     }
 };
 const rowControlHandler = {
-    ondragmove: function (point, index, component) {
+    ondragmove(point, index, component) {
         const { left, top, width, height } = component.textBounds;
         const heights_sum = component.heights_sum;
         const heights = component.heights.slice();
-        /* 컨트롤의 원래 위치를 구한다. */
         index -= component.columns - 1;
-        const origin_pos_unit = heights.slice(0, index + 1).reduce((sum, height) => sum + height, 0);
+        const origin_pos_unit = heights.slice(0, index + 1).reduce((sum, h) => sum + h, 0);
         const origin_offset = top + (origin_pos_unit / heights_sum) * height;
-        /*
-         * point의 좌표는 부모 레이어 기준의 x, y 값이다.
-         * 따라서, 도형의 회전을 감안한 좌표로의 변환이 필요하다.
-         * Transcoord시에는 point좌표가 부모까지 transcoord되어있는 상태이므로,
-         * 컴포넌트자신에 대한 transcoord만 필요하다.(마지막 파라미터를 false로).
-         */
         const transcoorded = component.transcoordP2S(point.x, point.y);
         const diff = transcoorded.y - origin_offset;
         let diff_unit = (diff / height) * heights_sum;
-        const min_height_unit = (heights_sum / height) * 5; // 5픽셀정도를 최소로
+        const min_height_unit = (heights_sum / height) * 5;
         if (diff_unit < 0)
             diff_unit = -Math.min(heights[index] - min_height_unit, -diff_unit);
         else
@@ -232,598 +107,1258 @@ const rowControlHandler = {
         component.set('heights', heights);
     }
 };
-let RackGrid = class RackGrid extends ContainerAbstract {
-    get state() {
-        return super.state;
-    }
-    _focused_cell;
-    // StockMaterialProvider 구현
-    _stock_materials = [];
-    _default_material;
-    _empty_material;
-    _legendTarget;
-    get legendTarget() {
-        const { legendTarget } = this.state;
-        if (!this._legendTarget && legendTarget) {
-            this._legendTarget = this.root.findById?.(legendTarget);
-            this._legendTarget?.on('change', this._onLegendChanged, this);
-        }
-        // 하위호환: 자체 legendTarget이 없으면 부모(Visualizer)의 legendTarget 폴백
-        if (!this._legendTarget) {
-            let ancestor = this.parent;
-            while (ancestor) {
-                if (ancestor.legendTarget)
-                    return ancestor.legendTarget;
-                ancestor = ancestor.parent;
-            }
-            // 서비스 레지스트리 폴백: stock-hub의 legendTarget
-            const stockHub = this.root?.getService?.('stock');
-            if (stockHub?.legendTarget)
-                return stockHub.legendTarget;
-        }
-        return this._legendTarget;
-    }
-    get hideEmptyStock() {
-        return !!this.getState('hideEmptyStock');
-    }
-    _onLegendChanged() {
-        this._resetMaterials();
-        this.invalidate();
+// ─── Nature ───────────────────────────────────────────────────────────────────
+//
+// `nature` 는 *static const* 가 아니라 *get nature()* — properties 의 widget event
+// handler 안 `this` 가 *해당 RackGrid 인스턴스* 를 가리키도록 (화살표 함수가
+// getter 의 `this` 를 capture). rack-table-cell 의 동일 패턴.
+// ─── RackGrid ─────────────────────────────────────────────────────────────────
+let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
+    static placement = 'floor';
+    static align = 'bottom';
+    static defaultDepth = (h) => h.ceiling - h.floor;
+    get nature() {
+        return {
+            mutable: false,
+            resizable: true,
+            rotatable: true,
+            properties: [
+                { type: 'number', label: 'columns', name: 'columns' },
+                { type: 'number', label: 'rows', name: 'rows' },
+                { type: 'number', label: 'shelves', name: 'shelves' },
+                { type: 'number', label: 'shelf-base-height', name: 'shelfBaseHeight' },
+                { type: 'string', label: 'zone', name: 'zone' },
+                { type: 'string', label: 'location-pattern', name: 'locPattern', placeholder: '{z}{s}-{u}-{sh}' },
+                { type: 'number', label: 'section-digits', name: 'sectionDigits' },
+                { type: 'number', label: 'unit-digits', name: 'unitDigits' },
+                { type: 'string', label: 'shelf-locations', name: 'shelfLocations', placeholder: '1,2,3 또는 ,,,04' },
+                {
+                    // root.selected 의 RackGridCell 들 또는 *전체 grid* 에 채번 적용.
+                    type: 'location-increase-pattern',
+                    label: '',
+                    name: '',
+                    property: {
+                        event: {
+                            'increase-location-pattern': (event) => {
+                                const { increasingDirection, skipNumbering, startSection, startUnit } = event.detail;
+                                const selected = this.root?.selected;
+                                const keys = (selected || [])
+                                    .filter(c => c?.state?.type === 'rack-grid-cell')
+                                    .map(c => c.state.cellId)
+                                    .filter((k) => !!k);
+                                this.increaseLocation(keys, increasingDirection, skipNumbering, startSection, startUnit);
+                            }
+                        }
+                    }
+                },
+                { type: 'checkbox', label: 'hide-rack-frame', name: 'hideRackFrame' },
+                { type: 'checkbox', label: 'hide-horizontal-frame', name: 'hideHorizontalFrame' },
+                { type: 'id-input', label: 'legend-target', name: 'legendTarget', property: { component: 'legend' } },
+                { type: 'checkbox', label: 'hide-empty-stock', name: 'hideEmptyStock' },
+                { type: 'id-input', label: 'popup-ref', name: 'popupRef', property: { component: 'popup' } }
+            ],
+            help: 'scene/component/rack-grid'
+        };
     }
-    _resetMaterials() {
-        this._stock_materials.forEach(m => m.dispose?.());
-        this._stock_materials = [];
-        delete this._default_material;
-        delete this._empty_material;
+    get anchors() {
+        return [];
     }
-    buildRealObject() {
-        return new RackGrid3D(this);
+    /**
+     * Serialize 시 자식 RackGridCell 의 redundant 속성 제거:
+     *  - 좌표/변환 (left/top/width/height/zPos/rotation/scale/translate) — table layout 이
+     *    runtime 에 자동 결정. state 저장하면 layout 결과와 불일치 위험.
+     *  - **refid** — *동적 생성* 되는 자식이라 *부모의 refid 가 그대로 들어가면 충돌*
+     *    ("Refid Index replaced" 경고). 자식의 refid 는 *load 시 새로 자동 부여*. (외부
+     *    참조용 *id* 는 사용자 명시 시만 유지)
+     *
+     * 유지: cellId, section, unit, isEmpty, border, shelfLocations 등 *own 데이터*.
+     */
+    get hierarchy() {
+        const base = super.hierarchy;
+        if (base?.components && Array.isArray(base.components)) {
+            base.components = base.components.map((c) => {
+                if (!c || typeof c !== 'object')
+                    return c;
+                const { left, top, width, height, zPos, rotation, scale, translate, refid, ...rest } = c;
+                return rest;
+            });
+        }
+        return base;
     }
-    dispose() {
-        this._legendTarget?.off('change', this._onLegendChanged, this);
-        delete this._legendTarget;
-        this._resetMaterials();
-        super.dispose();
-        delete this._focused_cell;
+    /** Focusible — children (RackGridCell) 도 editor 의 selection 가능 (rack-table 동일). */
+    get focusible() {
+        return false;
     }
+    /** Lifecycle — children 자동 생성. columns × rows 만큼 RackGridCell 자식. */
     created() {
-        const tobeSize = this.rows * this.columns;
-        const gap = this.size() - tobeSize;
-        if (gap == 0) {
+        const tobeSize = this.columns * this.rackRows;
+        const gap = (this.size?.() ?? this.components.length) - tobeSize;
+        if (gap === 0) {
+            // 자식 수는 맞음 — cellId 만 sync
+            this._syncChildCellIds();
             return;
         }
         else if (gap > 0) {
-            let removals = this.components.slice(gap);
-            this.remove(removals);
+            ;
+            this.remove?.(this.components.slice(gap));
         }
         else {
-            let newbies = [];
+            const newbies = [];
             for (let i = 0; i < -gap; i++)
                 newbies.push(buildNewCell(this.app));
-            this.add(newbies);
+            this.add?.(newbies);
         }
         const widths = this.getState('widths');
         const heights = this.getState('heights');
         if (!widths || widths.length < this.columns)
             this.set('widths', this.widths);
-        if (!heights || heights.length < this.rows)
+        if (!heights || heights.length < this.rackRows)
             this.set('heights', this.heights);
+        this._syncChildCellIds();
     }
-    // 컴포넌트를 임의로 추가 및 삭제할 수 있는 지를 지정하는 속성임.
-    get focusible() {
-        return false;
+    /** columns/rows 변경 시 children 재구성. rack-table.buildCells 패턴. */
+    onchange(after, _before) {
+        super.onchange?.(after, _before);
+        if ('columns' in after || 'rows' in after) {
+            const oldCols = _before.columns ?? this.columns;
+            const oldRows = _before.rows ?? this.rackRows;
+            this._buildCells(this.rackRows, this.columns, oldRows, oldCols);
+        }
+        // 룰 관련 변경 → location 역인덱스 무효화
+        if ('locPattern' in after || 'sectionDigits' in after || 'unitDigits' in after ||
+            'shelfLocations' in after || 'zone' in after || 'shelves' in after) {
+            this.invalidateLocationIndex();
+        }
+        // stock 시각 영향 속성 → InstancedMesh 재빌드
+        if ('data' in after || 'hideEmptyStock' in after || 'shelves' in after ||
+            'shelfBaseHeight' in after || 'width' in after || 'depth' in after ||
+            'height' in after || 'columns' in after || 'rows' in after) {
+            ;
+            this._realObject?.rebuildStockMesh?.();
+        }
+        // hideRackFrame / hideHorizontalFrame 변경 → frame visibility 즉시 토글
+        if ('hideRackFrame' in after || 'hideHorizontalFrame' in after) {
+            ;
+            this._realObject?.applyFrameVisibility?.();
+        }
     }
-    get widths() {
-        const widths = this.getState('widths');
-        if (!widths)
-            return array(1, this.columns);
-        if (widths.length < this.columns)
-            return widths.concat(array(1, this.columns - widths.length));
-        else if (widths.length > this.columns)
-            return widths.slice(0, this.columns);
-        return widths;
+    /** state.data 변경 시 호출 (things-scene 의 onchange<PropName>). */
+    onchangeData() {
+        ;
+        this._realObject?.rebuildStockMesh?.();
     }
-    get heights() {
-        const heights = this.getState('heights');
-        if (!heights)
-            return array(1, this.rows);
-        if (heights.length < this.rows)
-            return heights.concat(array(1, this.rows - heights.length));
-        else if (heights.length > this.rows)
-            return heights.slice(0, this.rows);
-        return heights;
+    /** state.data 의 records — Plan A 의 stock 보관소. */
+    get records() {
+        return this.state.data ?? [];
+    }
+    // ── Legend integration ──────────────────────────────────
+    _legendTarget;
+    /**
+     * Legend 컴포넌트 lookup. 우선순위:
+     *   1) state.legendTarget id 명시
+     *   2) scene 전체 의 type='legend' 첫 번째 컴포넌트 (자동 발견)
+     */
+    get legendTarget() {
+        if (this._legendTarget)
+            return this._legendTarget;
+        const id = this.state.legendTarget;
+        if (id) {
+            const found = this.root?.findById?.(id);
+            if (found) {
+                this._legendTarget = found;
+                found.on?.('change', this._onLegendChanged, this);
+                return found;
+            }
+        }
+        const visit = (node) => {
+            if (!node)
+                return undefined;
+            if (node.state?.type === 'legend')
+                return node;
+            const children = node.components;
+            if (children) {
+                for (const c of children) {
+                    const r = visit(c);
+                    if (r)
+                        return r;
+                }
+            }
+            return undefined;
+        };
+        const found = visit(this.root);
+        if (found) {
+            this._legendTarget = found;
+            found.on?.('change', this._onLegendChanged, this);
+        }
+        return found;
+    }
+    _onLegendChanged = () => {
+        ;
+        this._realObject?.rebuildStockMesh?.();
+    };
+    /**
+     * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+     *   - `range.value === recordValue` (카테고리 일치)
+     *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+     *   - 매칭 없으면 `defaultColor` 또는 undefined
+     */
+    // ── View-mode click → rack-grid-cell-click event + popup ──
+    get eventMap() {
+        return {
+            '(self)': {
+                '(self)': {
+                    click: this._onViewClick
+                }
+            }
+        };
     }
-    buildCells(newrows, newcolumns, oldrows, oldcolumns) {
+    _onViewClick = (mouseEvent) => {
+        if (!this.app?.isViewMode)
+            return;
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return;
+        const hit = this._raycastHit(mouseEvent);
+        if (!hit)
+            return;
+        const stockMesh = ro.stockMesh;
+        let cellId;
+        let record;
+        let isStock = false;
+        let instanceId;
+        if (hit.object === stockMesh) {
+            const records = stockMesh.userData?._records;
+            record = records?.[hit.instanceId ?? -1];
+            cellId = record?.cellId;
+            isStock = true;
+            instanceId = hit.instanceId;
+        }
+        else {
+            const cid = this._cellIdFromWorldPoint(hit.point);
+            if (!cid || cid.startsWith('out-of-bounds'))
+                return;
+            cellId = cid;
+            const data = this.state.data;
+            record = Array.isArray(data) ? data.find(r => r?.cellId === cid) : undefined;
+        }
+        const payload = { cellId, record, hitPoint: hit.point, instanceId, isStock };
+        this.trigger('rack-grid-cell-click', payload);
+        this._invokePopup(cellId, record);
+        // popup 외부 click 으로 인식되어 자동 close 되는 회귀 차단
+        mouseEvent.stopPropagation?.();
+    };
+    /** state.popupRef Popup 컴포넌트 invoke. anchor = 클릭된 cell 의 SlotTarget. */
+    _invokePopup(cellId, record) {
+        const popupRefId = this.state.popupRef;
+        if (!popupRefId || !cellId)
+            return;
+        const popupComp = this.root?.findById?.(popupRefId);
+        if (!popupComp || typeof popupComp.openPopup !== 'function') {
+            console.warn(`[rack-grid] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`);
+            return;
+        }
+        const anchor = this.slotTargetAt(cellId);
+        popupComp.openPopup(record ?? { cellId }, { anchor });
+    }
+    /** raycast → 우리 RackGrid 의 어떤 mesh 가 closest hit 인지. */
+    _raycastHit(mouseEvent) {
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return undefined;
+        const tc = ro.threeContainer;
+        if (!tc)
+            return undefined;
+        const cap = tc._threeCapability ?? tc._capability;
+        let intersects;
+        if (cap?.getObjectsByRaycast) {
+            intersects = cap.getObjectsByRaycast();
+        }
+        if (!intersects || intersects.length === 0) {
+            const scene = tc.scene3d;
+            const renderer = tc.renderer3d;
+            const camera = tc.activeCamera3d ??
+                cap?.activeCamera ??
+                cap?.camera;
+            const canvas = renderer?.domElement;
+            if (!scene || !canvas || !camera)
+                return undefined;
+            const rect = canvas.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0)
+                return undefined;
+            const ndc = new THREE.Vector2(((mouseEvent.clientX - rect.left) / rect.width) * 2 - 1, -((mouseEvent.clientY - rect.top) / rect.height) * 2 + 1);
+            const raycaster = new THREE.Raycaster();
+            raycaster.setFromCamera(ndc, camera);
+            intersects = raycaster.intersectObjects(scene.children, true);
+        }
+        if (!intersects || intersects.length === 0)
+            return undefined;
+        const closest = intersects[0];
+        let obj = closest.object;
+        while (obj) {
+            if (obj.userData?.context === ro)
+                return closest;
+            obj = obj.parent;
+        }
+        return undefined;
+    }
+    /** world point → cellId (col-row-shelf) 역산. */
+    _cellIdFromWorldPoint(worldPoint) {
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return null;
+        const local = new THREE.Vector3().copy(worldPoint);
+        const mInv = new THREE.Matrix4().copy(ro.object3d.matrixWorld).invert();
+        local.applyMatrix4(mInv);
+        const cols = this.columns;
+        const rows = this.rackRows;
+        const shelves = this.shelves;
+        const width = this.state.width || 1000;
+        const height = this.state.depth || 2000; // 3D Y
+        const depth = this.state.height || 200; // 3D Z
+        const shelfBase = this.state.shelfBaseHeight || 0;
+        const shelfZone = height - shelfBase;
+        const bayW = width / cols;
+        const bayD = depth / rows;
+        const cellY = shelfZone / shelves;
+        // center-based: X [-width/2, +width/2], Y [-height/2, +height/2], Z [-depth/2, +depth/2]
+        const col = Math.floor((local.x + width / 2) / bayW);
+        const yFromBottom = local.y + height / 2 - shelfBase;
+        const shelf = Math.floor(yFromBottom / cellY);
+        const row = Math.floor((local.z + depth / 2) / bayD);
+        if (col < 0 || col >= cols || row < 0 || row >= rows || shelf < 0 || shelf >= shelves) {
+            return `out-of-bounds(col=${col},row=${row},shelf=${shelf})`;
+        }
+        return `${col}-${row}-${shelf}`;
+    }
+    resolveLegendColor(record) {
+        const legend = this.legendTarget;
+        if (!legend)
+            return undefined;
+        const status = legend.getState?.('status') ?? legend.state?.status;
+        if (!status)
+            return undefined;
+        const field = status.field;
+        const ranges = status.ranges;
+        if (!field || !Array.isArray(ranges))
+            return undefined;
+        const value = record?.[field];
+        if (value === undefined || value === null)
+            return status.defaultColor;
+        for (const range of ranges) {
+            if (!range)
+                continue;
+            if (range.value !== undefined) {
+                if (range.value === value)
+                    return range.color;
+                continue;
+            }
+            const num = Number(value);
+            if (!Number.isFinite(num))
+                continue;
+            const min = range.min !== undefined && range.min !== '' ? Number(range.min) : undefined;
+            const max = range.max !== undefined && range.max !== '' ? Number(range.max) : undefined;
+            const minOk = min === undefined || num >= min;
+            const maxOk = max === undefined || num < max;
+            if (minOk && maxOk)
+                return range.color;
+        }
+        return status.defaultColor;
+    }
+    /**
+     * 새 (rows × columns) 에 맞춰 children 재구성. rack-table.buildCells 정확 클론.
+     */
+    _buildCells(newrows, newcolumns, oldrows, oldcolumns) {
+        const app = this.app;
         if (newrows < oldrows) {
-            let removals = this.components.slice(oldcolumns * newrows);
-            this.remove(removals);
+            const removals = this.components.slice(oldcolumns * newrows);
+            this.remove?.(removals);
         }
         const minrows = Math.min(newrows, oldrows);
         if (newcolumns > oldcolumns) {
             for (let r = 0; r < minrows; r++) {
                 for (let c = oldcolumns; c < newcolumns; c++) {
-                    this.insertComponentAt(buildNewCell(this.app), r * newcolumns + c);
+                    ;
+                    this.insertComponentAt?.(buildNewCell(app), r * newcolumns + c);
                 }
             }
         }
         else if (newcolumns < oldcolumns) {
-            let removals = [];
+            const removals = [];
             for (let r = 0; r < minrows; r++) {
                 for (let c = newcolumns; c < oldcolumns; c++) {
                     removals.push(this.components[r * oldcolumns + c]);
                 }
             }
-            this.remove(removals);
+            ;
+            this.remove?.(removals);
         }
         if (newrows > oldrows) {
-            let newbies = [];
+            const newbies = [];
             for (let r = oldrows; r < newrows; r++) {
-                for (let i = 0; i < newcolumns; i++) {
-                    newbies.push(buildNewCell(this.app));
-                }
+                for (let i = 0; i < newcolumns; i++)
+                    newbies.push(buildNewCell(app));
             }
-            this.add(newbies);
+            ;
+            this.add?.(newbies);
         }
-        this.set({
-            widths: this.widths,
-            heights: this.heights
-        });
-    }
-    get layout() {
-        return TABLE_LAYOUT;
-    }
-    get rows() {
-        return this.getState('rows');
-    }
-    setCellsStyle(cells, style, where) {
-        const components = this.components;
-        const total = components.length;
-        const columns = this.getState('columns');
-        // 병합된 셀도 포함시킨다.
-        const _cells = [];
-        cells.forEach(c => {
-            _cells.push(c);
-            if (c.colspan || c.rowspan) {
-                let col = this.getRowColumn(c).column;
-                let row = this.getRowColumn(c).row;
-                for (let i = row; i < row + c.rowspan; i++)
-                    for (let j = col; j < col + c.colspan; j++)
-                        if (i != row || j != col)
-                            _cells.push(this.components[i * this.columns + j]);
-            }
-        });
-        const indices = _cells.map(cell => components.indexOf(cell));
-        indices.forEach(i => {
-            const cell = components[i];
-            switch (where) {
-                case 'all':
-                    setCellBorder(cell, style, where);
-                    if (isLeftMost(total, columns, indices, i))
-                        setCellBorder(components[before(columns, i)], style, 'right');
-                    if (isRightMost(total, columns, indices, i))
-                        setCellBorder(components[after(columns, i)], style, 'left');
-                    if (isTopMost(total, columns, indices, i))
-                        setCellBorder(components[above(columns, i)], style, 'bottom');
-                    if (isBottomMost(total, columns, indices, i))
-                        setCellBorder(components[below(columns, i)], style, 'top');
-                    break;
-                case 'in':
-                    if (!isLeftMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'left');
-                    }
-                    if (!isRightMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'right');
-                    }
-                    if (!isTopMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'top');
-                    }
-                    if (!isBottomMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'bottom');
-                    }
-                    break;
-                case 'out':
-                    if (isLeftMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'left');
-                        setCellBorder(components[before(columns, i)], style, 'right');
-                    }
-                    if (isRightMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'right');
-                        setCellBorder(components[after(columns, i)], style, 'left');
-                    }
-                    if (isTopMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'top');
-                        setCellBorder(components[above(columns, i)], style, 'bottom');
-                    }
-                    if (isBottomMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'bottom');
-                        setCellBorder(components[below(columns, i)], style, 'top');
-                    }
-                    break;
-                case 'left':
-                    if (isLeftMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'left');
-                        setCellBorder(components[before(columns, i)], style, 'right');
-                    }
-                    break;
-                case 'right':
-                    if (isRightMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'right');
-                        setCellBorder(components[after(columns, i)], style, 'left');
-                    }
-                    break;
-                case 'center':
-                    if (!isLeftMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'left');
-                    }
-                    if (!isRightMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'right');
-                    }
-                    break;
-                case 'middle':
-                    if (!isTopMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'top');
-                    }
-                    if (!isBottomMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'bottom');
-                    }
-                    break;
-                case 'top':
-                    if (isTopMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'top');
-                        setCellBorder(components[above(columns, i)], style, 'bottom');
-                    }
-                    break;
-                case 'bottom':
-                    if (isBottomMost(total, columns, indices, i)) {
-                        setCellBorder(cell, style, 'bottom');
-                        setCellBorder(components[below(columns, i)], style, 'top');
-                    }
-                    break;
-                case 'clear':
-                    setCellBorder(cell, CLEAR_STYLE, 'all');
-                    if (isLeftMost(total, columns, indices, i))
-                        setCellBorder(components[before(columns, i)], CLEAR_STYLE, 'right');
-                    if (isRightMost(total, columns, indices, i))
-                        setCellBorder(components[after(columns, i)], CLEAR_STYLE, 'left');
-                    if (isTopMost(total, columns, indices, i))
-                        setCellBorder(components[above(columns, i)], CLEAR_STYLE, 'bottom');
-                    if (isBottomMost(total, columns, indices, i))
-                        setCellBorder(components[below(columns, i)], CLEAR_STYLE, 'top');
-            }
-        });
+        this.set({ widths: this.widths, heights: this.heights });
+        this._syncChildCellIds();
     }
-    getRowColumn(cell) {
-        const idx = this.components.indexOf(cell);
-        return {
-            column: idx % this.columns,
-            row: Math.floor(idx / this.columns)
-        };
+    /** children 의 state.cellId 가 *순서 기반 bayKey* 와 일치하도록 동기화. */
+    _syncChildCellIds() {
+        const cols = this.columns;
+        const children = this.components;
+        for (let i = 0; i < children.length; i++) {
+            const col = i % cols;
+            const row = Math.floor(i / cols);
+            const bayKey = `${col}-${row}`;
+            const c = children[i];
+            if (c?.state?.cellId !== bayKey)
+                c?.set?.('cellId', bayKey);
+        }
     }
+    /** Row 인덱스의 cell 들. rack-table-cell 의 rowCells 가 사용. */
     getCellsByRow(row) {
         return this.components.slice(row * this.columns, (row + 1) * this.columns);
     }
+    /** Column 인덱스의 cell 들. */
     getCellsByColumn(column) {
-        const cells = [];
-        for (let i = 0; i < this.rows; i++)
-            cells.push(this.components[this.columns * i + column]);
-        return cells;
-    }
-    deleteRows(cells) {
-        // 먼저 cells 위치의 행을 구한다.
-        let rows = [];
-        cells.forEach(cell => {
-            let row = this.getRowColumn(cell).row;
-            if (-1 == rows.indexOf(row)) {
-                rows.push(row);
-            }
-        });
-        rows.sort((a, b) => {
-            return a - b;
-        });
-        rows.reverse();
-        const heights = this.heights.slice();
-        rows.forEach(row => {
-            this.remove(this.getCellsByRow(row));
-        });
-        rows.forEach(row => heights.splice(row, 1));
-        this.model.rows -= rows.length; // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
-        this.set('heights', heights);
-    }
-    deleteColumns(cells) {
-        // 먼저 cells 위치의 열을 구한다.
-        let columns = [];
-        cells.forEach(cell => {
-            let column = this.getRowColumn(cell).column;
-            if (-1 == columns.indexOf(column))
-                columns.push(column);
-        });
-        columns.sort((a, b) => {
-            return a - b;
-        });
-        columns.reverse();
-        columns.forEach(column => {
-            const widths = this.widths.slice();
-            this.remove(this.getCellsByColumn(column));
-            widths.splice(column, 1);
-            this.model.columns -= 1; // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
-            this.set('widths', widths);
-        });
-    }
-    insertCellsAbove(cells) {
-        // 먼저 cells 위치의 행을 구한다.
-        let rows = [];
-        cells.forEach(cell => {
-            let row = this.getRowColumn(cell).row;
-            if (-1 == rows.indexOf(row))
-                rows.push(row);
-        });
-        rows.sort((a, b) => {
-            return a - b;
-        });
-        rows.reverse();
-        // 행 2개 이상은 추가 안함. 임시로 막아놓음
-        if (rows.length >= 2)
-            return false;
-        let insertionRowPosition = rows[0];
-        let newbieRowHeights = [];
-        let newbieCells = [];
-        rows.forEach(row => {
-            for (let i = 0; i < this.columns; i++)
-                newbieCells.push(buildCopiedCell(this.components[row * this.columns + i].model, this.app));
-            newbieRowHeights.push(this.heights[row]);
-            newbieCells.reverse().forEach(cell => {
-                this.insertComponentAt(cell, insertionRowPosition * this.columns);
-            });
-            let heights = this.heights.slice();
-            heights.splice(insertionRowPosition, 0, ...newbieRowHeights);
-            this.set('heights', heights);
-            this.model.rows += rows.length;
-            this.clearCache();
-        });
-    }
-    insertCellsBelow(cells) {
-        // 먼저 cells 위치의 행을 구한다.
-        let rows = [];
-        cells.forEach(cell => {
-            let row = this.getRowColumn(cell).row;
-            if (-1 == rows.indexOf(row))
-                rows.push(row);
-        });
-        rows.sort((a, b) => {
-            return a - b;
-        });
-        rows.reverse();
-        // 행 2개 이상은 추가 안함. 임시로 막아놓음
-        if (rows.length >= 2)
-            return false;
-        let insertionRowPosition = rows[rows.length - 1] + 1;
-        let newbieRowHeights = [];
-        let newbieCells = [];
-        rows.forEach(row => {
-            for (let i = 0; i < this.columns; i++)
-                newbieCells.push(buildCopiedCell(this.components[row * this.columns + i].model, this.app));
-            newbieRowHeights.push(this.heights[row]);
-            newbieCells.reverse().forEach(cell => {
-                this.insertComponentAt(cell, insertionRowPosition * this.columns);
-            });
-            let heights = this.heights.slice();
-            heights.splice(insertionRowPosition, 0, ...newbieRowHeights);
-            this.set('heights', heights);
-            this.model.rows += 1;
-            this.clearCache();
-        });
-    }
-    insertCellsLeft(cells) {
-        // 먼저 cells 위치의 열을 구한다.
-        let columns = [];
-        cells.forEach(cell => {
-            let column = this.getRowColumn(cell).column;
-            if (-1 == columns.indexOf(column))
-                columns.push(column);
-        });
-        columns.sort((a, b) => {
-            return a - b;
-        });
-        columns.reverse();
-        // 열 2개 이상은 추가 안함. 임시로 막아놓음
-        if (columns.length >= 2)
-            return false;
-        let insertionColumnPosition = columns[0];
-        let newbieColumnWidths = [];
-        let newbieCells = [];
-        columns.forEach(column => {
-            for (let i = 0; i < this.rows; i++)
-                newbieCells.push(buildCopiedCell(this.components[column + this.columns * i].model, this.app));
-            newbieColumnWidths.push(this.widths[column]);
-            let increasedColumns = this.columns;
-            let index = this.rows;
-            newbieCells.reverse().forEach(cell => {
-                if (index == 0) {
-                    index = this.rows;
-                    increasedColumns++;
-                }
-                index--;
-                this.insertComponentAt(cell, insertionColumnPosition + index * increasedColumns);
-            });
-            let widths = this.widths.slice();
-            this.model.columns += columns.length; // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
-            widths.splice(insertionColumnPosition, 0, ...newbieColumnWidths);
-            this.set('widths', widths);
-        });
-    }
-    insertCellsRight(cells) {
-        // 먼저 cells 위치의 열을 구한다.
-        let columns = [];
-        cells.forEach(cell => {
-            let column = this.getRowColumn(cell).column;
-            if (-1 == columns.indexOf(column))
-                columns.push(column);
-        });
-        columns.sort((a, b) => {
-            return a - b;
-        });
-        columns.reverse();
-        // 열 2개 이상은 추가 안함. 임시로 막아놓음
-        if (columns.length >= 2)
-            return false;
-        let insertionColumnPosition = columns[columns.length - 1] + 1;
-        let newbieColumnWidths = [];
-        let newbieCells = [];
-        columns.forEach(column => {
-            for (let i = 0; i < this.rows; i++)
-                newbieCells.push(buildCopiedCell(this.components[column + this.columns * i].model, this.app));
-            newbieColumnWidths.push(this.widths[column]);
-            let increasedColumns = this.columns;
-            let index = this.rows;
-            newbieCells.reverse().forEach(cell => {
-                if (index == 0) {
-                    index = this.rows;
-                    increasedColumns++;
-                }
-                index--;
-                this.insertComponentAt(cell, insertionColumnPosition + index * increasedColumns);
-            });
-            let widths = this.widths.slice();
-            this.model.columns += columns.length; // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
-            widths.splice(insertionColumnPosition, 0, ...newbieColumnWidths);
-            this.set('widths', widths);
-        });
-    }
-    distributeHorizontal(cells) {
-        const columns = [];
-        cells.forEach(cell => {
-            let rowcolumn = this.getRowColumn(cell);
-            if (-1 == columns.indexOf(rowcolumn.column))
-                columns.push(rowcolumn.column);
-        });
-        const sum = columns.reduce((sum, column) => {
-            return sum + this.widths[column];
-        }, 0);
-        const newval = Math.round((sum / columns.length) * 100) / 100;
-        const widths = this.widths.slice();
-        columns.forEach(column => {
-            widths[column] = newval;
-        });
-        this.set('widths', widths);
-    }
-    distributeVertical(cells) {
-        const rows = [];
-        cells.forEach(cell => {
-            let rowcolumn = this.getRowColumn(cell);
-            if (-1 == rows.indexOf(rowcolumn.row))
-                rows.push(rowcolumn.row);
-        });
-        const sum = rows.reduce((sum, row) => {
-            return sum + this.heights[row];
-        }, 0);
-        const newval = Math.round((sum / rows.length) * 100) / 100;
-        const heights = this.heights.slice();
-        rows.forEach(row => {
-            heights[row] = newval;
-        });
-        this.set('heights', heights);
-    }
-    increaseLocation(type, skipNumbering, startSection, startUnit) {
-        const { sectionDigits = 2, unitDigits = 2 } = this.state;
-        const selectedCells = this.root.selected;
-        increaseLocation(selectedCells, type, skipNumbering, startSection, startUnit, sectionDigits, unitDigits);
-    }
-    get columns() {
-        return this.getState('columns');
+        const out = [];
+        for (let i = 0; i < this.rackRows; i++)
+            out.push(this.components[this.columns * i + column]);
+        return out;
     }
-    get lefts() {
-        return this.components.filter((c, i) => {
-            return !(i % this.columns);
-        });
+    /** (col, row) 위치의 cell-component. */
+    cellAt(col, row = 0) {
+        const idx = row * this.columns + col;
+        return this.components[idx] ?? null;
     }
-    get centers() {
-        return this.components.filter((c, i) => {
-            return i % this.columns && (i + 1) % this.columns;
-        });
+    /** bayKey 의 cell-component. */
+    cellAtBayKey(bayKey) {
+        const parsed = this.parsePosKey(bayKey);
+        if (!parsed)
+            return null;
+        return this.cellAt(parsed.col, parsed.row);
     }
-    get rights() {
-        return this.components.filter((c, i) => {
-            return !((i + 1) % this.columns);
-        });
+    /**
+     * (col, row) bay 가 *isEmpty* 인가. cell-component 의 state.isEmpty 가 source of
+     * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
+     */
+    isBayEmpty(col, row = 0) {
+        const cell = this.cellAt(col, row);
+        if (cell)
+            return !!cell.state.isEmpty;
+        const posKey = `${col}-${row}`;
+        return !!this.cellOverrides[posKey]?.isEmpty;
     }
-    get tops() {
-        return this.components.slice(0, this.columns);
+    buildRealObject() {
+        return new RackGrid3D(this);
     }
-    get middles() {
-        return this.components.slice(this.columns, this.columns * (this.rows - 1));
+    // ── Table layout — 자식 자동 배치 + columns/rows 의 가변 widths/heights ──
+    get layout() {
+        return TABLE_LAYOUT;
     }
-    get bottoms() {
-        return this.components.slice(this.columns * (this.rows - 1));
+    get widths() {
+        const widths = this.getState('widths');
+        if (!widths)
+            return arrayOf(1, this.columns);
+        if (widths.length < this.columns)
+            return widths.concat(arrayOf(1, this.columns - widths.length));
+        if (widths.length > this.columns)
+            return widths.slice(0, this.columns);
+        return widths;
     }
-    get all() {
-        return this.components;
+    get heights() {
+        const heights = this.getState('heights');
+        if (!heights)
+            return arrayOf(1, this.rackRows);
+        if (heights.length < this.rackRows)
+            return heights.concat(arrayOf(1, this.rackRows - heights.length));
+        if (heights.length > this.rackRows)
+            return heights.slice(0, this.rackRows);
+        return heights;
     }
     get widths_sum() {
-        const widths = this.widths;
-        return widths ? widths.filter((width, i) => i < this.columns).reduce((sum, width) => sum + width, 0) : this.columns;
+        return this.widths.reduce((sum, w) => sum + w, 0) || this.columns;
     }
     get heights_sum() {
-        const heights = this.heights;
-        return heights ? heights.filter((height, i) => i < this.rows).reduce((sum, height) => sum + height, 0) : this.rows;
-    }
-    get nature() {
-        return NATURE;
+        return this.heights.reduce((sum, h) => sum + h, 0) || this.rackRows;
     }
+    /** Column / Row 사이 드래그 핸들 — editor 의 widths/heights 가변 조절. */
     get controls() {
         const widths = this.widths;
         const heights = this.heights;
         const inside = this.textBounds;
         const width_unit = inside.width / this.widths_sum;
         const height_unit = inside.height / this.heights_sum;
-        let x = inside.left;
-        let y = inside.top;
         const controls = [];
-        widths.slice(0, this.columns - 1).forEach((width) => {
-            x += width * width_unit;
-            controls.push({
-                x: x,
-                y: inside.top,
-                handler: columnControlHandler
-            });
+        let x = inside.left;
+        widths.slice(0, this.columns - 1).forEach(w => {
+            x += w * width_unit;
+            controls.push({ x, y: inside.top, handler: columnControlHandler });
         });
-        heights.slice(0, this.rows - 1).forEach((height) => {
-            y += height * height_unit;
-            controls.push({
-                x: inside.left,
-                y: y,
-                handler: rowControlHandler
-            });
+        let y = inside.top;
+        heights.slice(0, this.rackRows - 1).forEach(h => {
+            y += h * height_unit;
+            controls.push({ x: inside.left, y, handler: rowControlHandler });
         });
         return controls;
     }
-    onchange(after, before) {
-        if ('legendTarget' in after || 'legendTarget' in before) {
-            this._legendTarget?.off('change', this._onLegendChanged, this);
-            delete this._legendTarget;
-            this._resetMaterials();
+    // ── 2D 렌더링 — table layout 의 widths/heights 기반 격자 ─────
+    //
+    // 자식 컴포넌트 가 자기 렌더링하지만 *비어있는 grid 도 modeling 시 가시화*. 격자
+    // 좌표는 widths/heights (table layout 의 가변 분할) 기반. cellOverrides 의
+    // isEmpty (사선) + border (4-side) 도 표시.
+    render(ctx) {
+        // 2D 에서는 hideRackFrame 이어도 *외곽 + 격자선 + cell 마커* 는 항상 그림.
+        // (2D 의 frame 은 시각적 *분할선* 이라 frame mesh 와 의미가 다름)
+        const inside = this.textBounds;
+        const left = inside.left;
+        const top = inside.top;
+        const width = inside.width;
+        const height = inside.height;
+        const cols = this.columns;
+        const rows = this.rackRows;
+        const widths = this.widths;
+        const heights = this.heights;
+        const wSum = this.widths_sum;
+        const hSum = this.heights_sum;
+        const fill = this.state.fillStyle || '#e8e8ec';
+        const stroke = this.state.strokeStyle || '#888';
+        const lineWidth = this.state.lineWidth || 1;
+        const overrides = this.cellOverrides;
+        // column 별 X 좌표 (좌→우 누적)
+        const xs = [left];
+        for (let c = 0; c < cols; c++)
+            xs.push(xs[c] + (widths[c] / wSum) * width);
+        // row 별 Y 좌표 (상→하 누적)
+        const ys = [top];
+        for (let r = 0; r < rows; r++)
+            ys.push(ys[r] + (heights[r] / hSum) * height);
+        // Fill (반투명) — 외곽 영역
+        ctx.save();
+        ctx.fillStyle = fill;
+        ctx.globalAlpha = 0.2;
+        ctx.fillRect(left, top, width, height);
+        ctx.restore();
+        // isEmpty cell 표시 (사선 + 회색 fill)
+        ctx.save();
+        for (const [posKey, ov] of Object.entries(overrides)) {
+            if (!ov.isEmpty)
+                continue;
+            const parsed = this.parsePosKey(posKey);
+            if (!parsed)
+                continue;
+            if (parsed.col < 0 || parsed.col >= cols || parsed.row < 0 || parsed.row >= rows)
+                continue;
+            const cl = xs[parsed.col];
+            const ct = ys[parsed.row];
+            const cw = xs[parsed.col + 1] - cl;
+            const ch = ys[parsed.row + 1] - ct;
+            ctx.fillStyle = '#cccccc';
+            ctx.globalAlpha = 0.5;
+            ctx.fillRect(cl, ct, cw, ch);
+            ctx.globalAlpha = 1;
+            ctx.strokeStyle = '#999';
+            ctx.lineWidth = 1;
+            ctx.beginPath();
+            ctx.moveTo(cl, ct);
+            ctx.lineTo(cl + cw, ct + ch);
+            ctx.moveTo(cl + cw, ct);
+            ctx.lineTo(cl, ct + ch);
+            ctx.stroke();
+        }
+        ctx.restore();
+        // 외곽 + 격자
+        ctx.save();
+        ctx.strokeStyle = stroke;
+        ctx.lineWidth = lineWidth;
+        ctx.strokeRect(left, top, width, height);
+        ctx.beginPath();
+        for (let c = 1; c < cols; c++) {
+            ctx.moveTo(xs[c], top);
+            ctx.lineTo(xs[c], top + height);
         }
-        if ('rows' in after || 'columns' in after) {
-            this.buildCells(this.getState('rows'), this.getState('columns'), before.hasOwnProperty('rows') ? before.rows : this.getState('rows'), before.hasOwnProperty('columns') ? before.columns : this.getState('columns'));
+        for (let r = 1; r < rows; r++) {
+            ctx.moveTo(left, ys[r]);
+            ctx.lineTo(left + width, ys[r]);
         }
-        this.invalidate();
+        ctx.stroke();
+        ctx.restore();
+        // cell 별 명시 border
+        for (const [posKey, ov] of Object.entries(overrides)) {
+            if (!ov.border)
+                continue;
+            const parsed = this.parsePosKey(posKey);
+            if (!parsed)
+                continue;
+            if (parsed.col < 0 || parsed.col >= cols || parsed.row < 0 || parsed.row >= rows)
+                continue;
+            const cl = xs[parsed.col];
+            const ct = ys[parsed.row];
+            const cr = xs[parsed.col + 1];
+            const cb = ys[parsed.row + 1];
+            const b = ov.border;
+            const drawSide = (style, x1, y1, x2, y2) => {
+                if (!style?.strokeStyle)
+                    return;
+                ctx.save();
+                ctx.strokeStyle = style.strokeStyle;
+                ctx.lineWidth = style.lineWidth ?? 1;
+                ctx.beginPath();
+                ctx.moveTo(x1, y1);
+                ctx.lineTo(x2, y2);
+                ctx.stroke();
+                ctx.restore();
+            };
+            drawSide(b.top, cl, ct, cr, ct);
+            drawSide(b.left, cl, ct, cl, cb);
+            drawSide(b.bottom, cl, cb, cr, cb);
+            drawSide(b.right, cr, ct, cr, cb);
+        }
+        // Selected bay 강조는 *rack-grid-cell 자체* 의 render 가 처리 (framework 의
+        // selection 시스템이 cell 의 outline 자동 그림). RackGrid 는 grid 골격만.
     }
-    get eventMap() {
+    // ── Grid layout ─────────────────────────────────────────
+    get columns() {
+        return Math.max(1, Math.floor(this.state.columns ?? 5));
+    }
+    get rackRows() {
+        return Math.max(1, Math.floor(this.state.rows ?? 1));
+    }
+    get shelves() {
+        return Math.max(1, Math.floor(this.state.shelves ?? 4));
+    }
+    // ── cellId / posKey 변환 ────────────────────────────────
+    /** posKey = `${col-1}-${row-1}` (0-based, 2 segments). 1-based input. */
+    posKeyOf(col, row = 1) {
+        return `${col - 1}-${row - 1}`;
+    }
+    /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
+    cellIdOf(col, row = 1, shelf = 1) {
+        return `${col - 1}-${row - 1}-${shelf - 1}`;
+    }
+    parseCellId(cellId) {
+        const parts = cellId.split('-');
+        if (parts.length !== 3)
+            return null;
+        const [c, r, s] = parts.map(Number);
+        if (!Number.isFinite(c) || !Number.isFinite(r) || !Number.isFinite(s))
+            return null;
+        return { col: c, row: r, shelf: s };
+    }
+    parsePosKey(posKey) {
+        const parts = posKey.split('-');
+        if (parts.length !== 2)
+            return null;
+        const [c, r] = parts.map(Number);
+        if (!Number.isFinite(c) || !Number.isFinite(r))
+            return null;
+        return { col: c, row: r };
+    }
+    // ── cellOverrides accessor ─────────────────────────────
+    get cellOverrides() {
+        return (this.state.cellOverrides ?? {});
+    }
+    getCellOverride(posKey) {
+        return this.cellOverrides[posKey];
+    }
+    // ── Shelf labels ───────────────────────────────────────
+    /**
+     * Parse `state.shelfLocations` 를 levels 길이 array 로. 빈 슬롯은 1-based index default.
+     *   '1,2,3'    → ['1', '2', '3', ...]
+     *   ',,,04'    → ['1', '2', '3', '04']
+     *   undefined  → ['1', '2', '3', '4', ...]
+     */
+    get shelfLabels() {
+        const input = this.state.shelfLocations;
+        const levels = this.shelves;
+        const parts = (input || '').split(',');
+        const out = [];
+        for (let i = 0; i < levels; i++) {
+            const p = parts[i];
+            out[i] = p && p.trim().length > 0 ? p.trim() : String(i + 1);
+        }
+        return out;
+    }
+    // ── Location 변환 (양방향) ──────────────────────────────
+    /**
+     * cellId → location string. 우선순위:
+     *   1. cell-component (state.section/unit) — source of truth
+     *   2. cellOverrides[posKey] — 호환성 fallback
+     * section/unit 둘 다 있고 isEmpty=false 일 때만 부여. 미부여 시 null.
+     */
+    locationOf(cellId) {
+        const parsed = this.parseCellId(cellId);
+        if (!parsed)
+            return null;
+        const posKey = `${parsed.col}-${parsed.row}`;
+        let section;
+        let unit;
+        let isEmpty;
+        let cellShelfLocations;
+        const cell = this.cellAt(parsed.col, parsed.row);
+        if (cell) {
+            section = cell.state.section;
+            unit = cell.state.unit;
+            isEmpty = cell.state.isEmpty;
+            cellShelfLocations = cell.state.shelfLocations;
+        }
+        else {
+            const override = this.cellOverrides[posKey];
+            section = override?.section;
+            unit = override?.unit;
+            isEmpty = override?.isEmpty;
+        }
+        if (!section || !unit || isEmpty)
+            return null;
+        const pattern = this.state.locPattern ?? '{z}{s}-{u}-{sh}';
+        const zone = this.state.zone ?? '';
+        const shelfLabel = this._shelfLabelsFromCell(cellShelfLocations)[parsed.shelf] ?? String(parsed.shelf + 1);
+        return pattern
+            .replace(/\{z\}/g, zone)
+            .replace(/\{s\}/g, section)
+            .replace(/\{u\}/g, unit)
+            .replace(/\{sh\}/g, shelfLabel);
+    }
+    /** cell.state.shelfLocations 명시 시 그것, 아니면 RackGrid 의 shelfLabels. */
+    _shelfLabelsFromCell(cellShelfLocations) {
+        const input = cellShelfLocations ?? this.state.shelfLocations;
+        const levels = this.shelves;
+        const parts = (input || '').split(',');
+        const out = [];
+        for (let i = 0; i < levels; i++) {
+            const p = parts[i];
+            out[i] = p && p.trim().length > 0 ? p.trim() : String(i + 1);
+        }
+        return out;
+    }
+    /** location string → cellId. sparse 역인덱스 lookup. 없으면 null. */
+    cellIdOfLocation(location) {
+        return this._locationIndex.get(location) ?? null;
+    }
+    /** 모든 (override 명시된) cell 의 location 목록. inspection 용. */
+    get allLocations() {
+        const result = [];
+        for (const [location, cellId] of this._locationIndex.entries()) {
+            result.push({ cellId, location });
+        }
+        return result;
+    }
+    // ── Location 역인덱스 (sparse cache) ────────────────────
+    _locationIndexCache;
+    get _locationIndex() {
+        if (this._locationIndexCache)
+            return this._locationIndexCache;
+        const map = new Map();
+        const shelves = this.shelves;
+        // 1. cell-component 들 (source of truth) — 모든 bay 순회
+        const cells = this.components;
+        if (cells && cells.length > 0) {
+            for (let i = 0; i < cells.length; i++) {
+                const cell = cells[i];
+                if (cell?.state?.type !== 'rack-grid-cell')
+                    continue;
+                const bayKey = cell.state.cellId;
+                if (!bayKey)
+                    continue;
+                const parsed = this.parsePosKey(bayKey);
+                if (!parsed)
+                    continue;
+                for (let shelfIdx = 0; shelfIdx < shelves; shelfIdx++) {
+                    const cellId = `${parsed.col}-${parsed.row}-${shelfIdx}`;
+                    const loc = this.locationOf(cellId);
+                    if (loc)
+                        map.set(loc, cellId);
+                }
+            }
+        }
+        // 2. cellOverrides fallback (cell-component 없는 시점 — 호환)
+        const overrides = this.cellOverrides;
+        for (const posKey of Object.keys(overrides)) {
+            const override = overrides[posKey];
+            if (!override.section || !override.unit || override.isEmpty)
+                continue;
+            const parsed = this.parsePosKey(posKey);
+            if (!parsed)
+                continue;
+            for (let shelfIdx = 0; shelfIdx < shelves; shelfIdx++) {
+                const cellId = `${parsed.col}-${parsed.row}-${shelfIdx}`;
+                if (!map.has(this.locationOf(cellId) || '')) {
+                    const loc = this.locationOf(cellId);
+                    if (loc && !map.has(loc))
+                        map.set(loc, cellId);
+                }
+            }
+        }
+        this._locationIndexCache = map;
+        return map;
+    }
+    /** 룰 / cellOverrides 변경 시 호출. things-scene 의 onchange* 가 자동 호출. */
+    invalidateLocationIndex() {
+        this._locationIndexCache = undefined;
+    }
+    onchangeCellOverrides() { this.invalidateLocationIndex(); }
+    onchangeLocPattern() { this.invalidateLocationIndex(); }
+    onchangeShelfLocations() { this.invalidateLocationIndex(); }
+    onchangeZone() { this.invalidateLocationIndex(); }
+    onchangeSectionDigits() { this.invalidateLocationIndex(); }
+    onchangeUnitDigits() { this.invalidateLocationIndex(); }
+    onchangeShelves() { this.invalidateLocationIndex(); }
+    // ── 자식 lookup ────────────────────────────────────────
+    /**
+     * (col, row) 위치의 자식 StorageRack. 자식이 StorageRack 이 아닌 경우 (Crane, AGV 등)
+     * 는 null — Carrier 보관은 StorageRack 만.
+     *
+     * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
+     * 자식 추가 시 자동 할당 또는 사용자가 명시.
+     */
+    _childRackAt(posKey) {
+        const parsed = this.parsePosKey(posKey);
+        if (!parsed)
+            return null;
+        const children = this.components ?? [];
+        for (const c of children) {
+            const type = c.state?.type;
+            if (type !== 'storage-rack')
+                continue;
+            const childCol = (c.state?.column ?? 1) - 1;
+            const childRow = (c.state?.row ?? 1) - 1;
+            if (childCol === parsed.col && childRow === parsed.row) {
+                return c;
+            }
+        }
+        return null;
+    }
+    // ── SlottedHolder 컨트랙 — 자식 StorageRack 으로 위임 ────
+    hasCarrierAt(slotId) {
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return false;
+        const child = this._childRackAt(`${parsed.col}-${parsed.row}`);
+        return child?.hasCarrierAt(`0-0-${parsed.shelf}`) ?? false;
+    }
+    obtainCarrier(slotIdOrLocation) {
+        const slotId = this._resolveToCellId(slotIdOrLocation);
+        if (!slotId)
+            return null;
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return null;
+        const child = this._childRackAt(`${parsed.col}-${parsed.row}`);
+        return child?.obtainCarrier(`0-0-${parsed.shelf}`) ?? null;
+    }
+    canReceiveAt(slotIdOrLocation, carrier) {
+        const slotId = this._resolveToCellId(slotIdOrLocation);
+        if (!slotId)
+            return false;
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return false;
+        // isEmpty 위치 는 carrier 못 받음 (location-less, modeling 차원)
+        const override = this.cellOverrides[`${parsed.col}-${parsed.row}`];
+        if (override?.isEmpty)
+            return false;
+        const child = this._childRackAt(`${parsed.col}-${parsed.row}`);
+        return child?.canReceiveAt(`0-0-${parsed.shelf}`, carrier) ?? false;
+    }
+    async receiveAt(slotIdOrLocation, carrier, options) {
+        const slotId = this._resolveToCellId(slotIdOrLocation);
+        if (!slotId)
+            throw new Error(`RackGrid.receiveAt: cannot resolve "${slotIdOrLocation}"`);
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            throw new Error(`RackGrid.receiveAt: invalid cellId "${slotId}"`);
+        const child = this._childRackAt(`${parsed.col}-${parsed.row}`);
+        if (!child) {
+            throw new Error(`RackGrid.receiveAt: no StorageRack at posKey=${parsed.col}-${parsed.row}`);
+        }
+        return child.receiveAt(`0-0-${parsed.shelf}`, carrier, options);
+    }
+    recordFromCarrier(carrier, slotId) {
+        const { id, refid, transform, ...rest } = (carrier.state || {});
+        return { ...rest, cellId: slotId };
+    }
+    /**
+     * Slot 의 attach object3d — Stock InstancedMesh 의 instance 와 *같은 world 위치* 에
+     * 위치한 invisible Object3D. popup tether / Carriable.applyHolderAttachPoint 가 이
+     * object3d 의 matrixWorld 를 사용. lazy 생성 + cache.
+     */
+    _attachAnchorByCell = new Map();
+    getSlotAttachObject3d(slotId) {
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return undefined;
+        if (parsed.col < 0 || parsed.col >= this.columns)
+            return undefined;
+        if (parsed.row < 0 || parsed.row >= this.rackRows)
+            return undefined;
+        if (parsed.shelf < 0 || parsed.shelf >= this.shelves)
+            return undefined;
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return undefined;
+        let obj = this._attachAnchorByCell.get(slotId);
+        if (!obj) {
+            obj = new THREE.Object3D();
+            obj.name = `rack-grid-anchor:${slotId}`;
+            ro.object3d.add(obj);
+            this._attachAnchorByCell.set(slotId, obj);
+        }
+        // 위치 갱신 — Stock InstancedMesh 의 instance 위치 와 동일 공식
+        const rs = this.state;
+        const cols = this.columns;
+        const rows = this.rackRows;
+        const shelves = this.shelves;
+        const width = rs?.width ?? 400;
+        const height = rs?.depth ?? 2000;
+        const depth = rs?.height ?? 200;
+        const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 0, height * 0.9));
+        const shelfZone = height - shelfBase;
+        const bayW = width / cols;
+        const bayD = depth / rows;
+        const cellY = shelfZone / shelves;
+        const baseY = -height / 2;
+        const shelfBaseY = baseY + shelfBase;
+        const stockD = cellY * 0.7;
+        const cx = (parsed.col - cols / 2 + 0.5) * bayW;
+        const cellBottomY = shelfBaseY + parsed.shelf * cellY;
+        const cy = cellBottomY + stockD / 2;
+        const cz = (parsed.row - rows / 2 + 0.5) * bayD;
+        obj.position.set(cx, cy, cz);
+        // *parent 의 matrixWorld 가 dirty 면 자식 matrixWorld 도 dirty* — 강제 갱신.
+        ro.object3d.updateMatrixWorld(true);
+        obj.updateMatrixWorld(true);
+        return obj;
+    }
+    getSlotSize(slotId) {
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return undefined;
+        const rs = this.state;
+        const width = rs?.width ?? 400;
+        const height = rs?.depth ?? 2000;
+        const depth = rs?.height ?? 200;
+        const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 0, height * 0.9));
+        const shelfZone = height - shelfBase;
+        const cellY = shelfZone / this.shelves;
         return {
-            '(self)': {
-                '(descendant)': {
-                    change: this.oncellchanged
+            width: (width / this.columns) * 0.85,
+            height: (depth / this.rackRows) * 0.85, // 2D height = 3D Z 폭
+            depth: cellY * 0.7 // 3D Y 폭 (= stockD)
+        };
+    }
+    cellCenter2D(slotId) {
+        const parsed = this.parseCellId(slotId);
+        if (!parsed)
+            return null;
+        const rs = this.state;
+        const left = rs?.left ?? 0;
+        const top = rs?.top ?? 0;
+        const width = rs?.width ?? 400;
+        const height = rs?.height ?? 200;
+        // table layout 의 widths/heights 비례 위치
+        const widths = this.widths;
+        const heights = this.heights;
+        const wSum = this.widths_sum;
+        const hSum = this.heights_sum;
+        let cumW = 0;
+        for (let c = 0; c < parsed.col; c++)
+            cumW += widths[c];
+        let cumH = 0;
+        for (let r = 0; r < parsed.row; r++)
+            cumH += heights[r];
+        const x = left + (cumW + widths[parsed.col] / 2) / wSum * width;
+        const y = top + (cumH + heights[parsed.row] / 2) / hSum * height;
+        return { x, y };
+    }
+    slotTargetAt(slotIdOrLocation) {
+        const slotId = this._resolveToCellId(slotIdOrLocation);
+        if (!slotId)
+            throw new Error(`RackGrid.slotTargetAt: cannot resolve "${slotIdOrLocation}"`);
+        return new SlotTarget(this, slotId);
+    }
+    // ── Helpers ──────────────────────────────────────────
+    /**
+     * 외부 입력 → 내부 cellId 변환:
+     *   - "N-N-N" (3 segments, 모두 숫자) → cellId 그대로 (dual-accept)
+     *   - 그 외 → location 으로 간주, locationIndex lookup
+     */
+    _resolveToCellId(input) {
+        if (this._isCellIdFormat(input))
+            return input;
+        return this.cellIdOfLocation(input);
+    }
+    _isCellIdFormat(s) {
+        const parts = s.split('-');
+        return parts.length === 3 && parts.every(p => /^\d+$/.test(p));
+    }
+    // ── Bulk 편집 API ────────────────────────────────────────
+    //
+    // 모두 *single setState* 로 cellOverrides 갱신 → 단일 'change' 이벤트만 발사.
+    // 매핑 cascade 회피 위해 silent 갱신 메서드 제공 (`_setCellOverridesSilently`).
+    /**
+     * 한 위치의 cellOverride 를 갱신 (merge). 기존 필드는 유지, 새 필드만 덮어씀.
+     * `partial` 의 필드가 *undefined* 면 *그 필드 삭제* (override 키에서 제거).
+     */
+    setCellOverride(posKey, partial) {
+        const current = this.cellOverrides;
+        const existing = current[posKey] ?? {};
+        const merged = { ...existing };
+        for (const [k, v] of Object.entries(partial)) {
+            if (v === undefined)
+                delete merged[k];
+            else
+                merged[k] = v;
+        }
+        const next = { ...current };
+        if (Object.keys(merged).length === 0)
+            delete next[posKey];
+        else
+            next[posKey] = merged;
+        this.setState({ cellOverrides: next });
+    }
+    /** 한 위치의 override 전체 삭제. */
+    clearCellOverride(posKey) {
+        const current = this.cellOverrides;
+        if (!(posKey in current))
+            return;
+        const next = { ...current };
+        delete next[posKey];
+        this.setState({ cellOverrides: next });
+    }
+    /**
+     * 여러 위치의 isEmpty 일괄 토글. cell-component 있으면 cell.set(), 없으면 cellOverrides.
+     */
+    setIsEmpty(posKeys, isEmpty) {
+        const hasCells = this.components.some((c) => c?.state?.type === 'rack-grid-cell');
+        if (hasCells) {
+            for (const posKey of posKeys) {
+                const cell = this.cellAtBayKey(posKey);
+                cell?.set?.('isEmpty', isEmpty);
+            }
+            this.invalidateLocationIndex();
+            return;
+        }
+        // Fallback: cellOverrides
+        const current = this.cellOverrides;
+        const next = { ...current };
+        for (const posKey of posKeys) {
+            const existing = next[posKey] ?? {};
+            const merged = { ...existing, isEmpty };
+            if (!isEmpty && !existing.section && !existing.unit && !existing.border && !existing.merged) {
+                delete next[posKey];
+            }
+            else {
+                next[posKey] = merged;
+            }
+        }
+        this.setState({ cellOverrides: next });
+    }
+    /**
+     * 여러 위치의 border 스타일 일괄 설정. `where` ('top'|'left'|'bottom'|'right'|'all').
+     *   - style = null → 해당 side 삭제
+     *   - where = 'all' → 4면 모두 동일 style
+     */
+    setBorder(posKeys, style, where = 'all') {
+        const sides = where === 'all' ? ['top', 'left', 'bottom', 'right'] : [where];
+        const current = this.cellOverrides;
+        const next = { ...current };
+        for (const posKey of posKeys) {
+            const existing = next[posKey] ?? {};
+            const border = { ...(existing.border ?? {}) };
+            for (const side of sides) {
+                if (style == null)
+                    delete border[side];
+                else
+                    border[side] = style;
+            }
+            const merged = { ...existing, border };
+            if (Object.keys(border).length === 0)
+                delete merged.border;
+            next[posKey] = merged;
+        }
+        this.setState({ cellOverrides: next });
+    }
+    /**
+     * 자동 채번 — 선택된 cell 들에 section/unit 자동 부여.
+     *
+     * @param posKeys     채번 대상 (선택 영역). 빈 array 면 *전체 grid*.
+     * @param direction   순회 방향:
+     *                      'cw'              — 한 row 내 col 증가 → 다음 row 는 반대 방향 (boustrophedon)
+     *                      'ccw'             — 반대 방향
+     *                      'zigzag'          — col 우선 증가 (cw 의 90° 회전)
+     *                      'zigzag-reverse'  — 반대
+     * @param skipNumbering  true 면 isEmpty cell 건너뜀 (단위 번호 안 증가).
+     * @param startSection   첫 section 번호 (default 1)
+     * @param startUnit      첫 unit 번호 (default 1)
+     *
+     * Aisle row (모든 cell isEmpty) 는 section 경계로 인식 — section 번호가 다음 row 에서 +1.
+     *
+     * setState 한 번 (cellOverrides 일괄 갱신) → location 역인덱스 1회 무효화.
+     */
+    increaseLocation(posKeys, direction = 'cw', skipNumbering = false, startSection = 1, startUnit = 1) {
+        const sectionDigits = Math.max(1, Math.floor(this.state.sectionDigits ?? 2));
+        const unitDigits = Math.max(1, Math.floor(this.state.unitDigits ?? 2));
+        // 대상 결정: posKeys 비었으면 전체 grid
+        const targets = posKeys.length > 0
+            ? [...posKeys]
+            : this._allPosKeys();
+        // (1) row 별 분류 (2D 배열, [row][col] = posKey)
+        const byRow = [];
+        let maxRow = -1;
+        let maxCol = -1;
+        for (const posKey of targets) {
+            const parsed = this.parsePosKey(posKey);
+            if (!parsed)
+                continue;
+            if (!byRow[parsed.row])
+                byRow[parsed.row] = [];
+            byRow[parsed.row][parsed.col] = posKey;
+            if (parsed.row > maxRow)
+                maxRow = parsed.row;
+            if (parsed.col > maxCol)
+                maxCol = parsed.col;
+        }
+        // (2) aisle row 식별 — row 의 모든 (선택된) cell 이 isEmpty
+        const overrides = this.cellOverrides;
+        const isAisleRow = (row) => {
+            const cells = byRow[row];
+            if (!cells || cells.length === 0)
+                return true;
+            return cells.every(p => p == null || overrides[p]?.isEmpty === true);
+        };
+        // (3) section 별 묶기 (aisle 사이의 연속 row 들)
+        const sections = [];
+        let currentSection = [];
+        for (let r = 0; r <= maxRow; r++) {
+            if (!byRow[r])
+                continue;
+            if (isAisleRow(r)) {
+                if (currentSection.length > 0) {
+                    sections.push(currentSection);
+                    currentSection = [];
                 }
             }
+            else {
+                currentSection.push(r);
+            }
+        }
+        if (currentSection.length > 0)
+            sections.push(currentSection);
+        // (4) 방향별 순회로 (section, unit) 부여
+        const hasCells = this.components.some((c) => c?.state?.type === 'rack-grid-cell');
+        const next = { ...overrides };
+        let sectionNum = Number(startSection) || 1;
+        const setSU = (posKey, section, unit) => {
+            const sStr = String(section).padStart(sectionDigits, '0');
+            const uStr = String(unit).padStart(unitDigits, '0');
+            if (hasCells) {
+                const cell = this.cellAtBayKey(posKey);
+                cell?.set?.('section', sStr);
+                cell?.set?.('unit', uStr);
+            }
+            else {
+                const existing = next[posKey] ?? {};
+                next[posKey] = { ...existing, section: sStr, unit: uStr };
+            }
+        };
+        const clearSU = (posKey) => {
+            if (hasCells) {
+                const cell = this.cellAtBayKey(posKey);
+                cell?.set?.('section', null);
+                cell?.set?.('unit', null);
+            }
+            else {
+                const existing = next[posKey];
+                if (!existing)
+                    return;
+                const { section, unit, ...rest } = existing;
+                if (Object.keys(rest).length === 0)
+                    delete next[posKey];
+                else
+                    next[posKey] = rest;
+            }
         };
+        for (const sectionRows of sections) {
+            for (const row of sectionRows) {
+                const cells = byRow[row];
+                if (!cells)
+                    continue;
+                // 방향별 cell 순회 순서 결정
+                const orderedCols = this._orderCols(row, sectionRows, direction, maxCol);
+                let unitNum = Number(startUnit) || 1;
+                for (const col of orderedCols) {
+                    const posKey = cells[col];
+                    if (!posKey)
+                        continue;
+                    const isEmpty = overrides[posKey]?.isEmpty === true;
+                    if (isEmpty) {
+                        clearSU(posKey);
+                        if (!skipNumbering)
+                            unitNum++;
+                    }
+                    else {
+                        setSU(posKey, sectionNum, unitNum);
+                        unitNum++;
+                    }
+                }
+                // row 마다 section 증가? 아님 — section 은 *aisle 로 구분된 묶음 단위*.
+                // 동일 section 내 다음 row 는 unit 번호 다시 startUnit 부터.
+                // rack-table 의 원본 동작과 동일.
+            }
+            sectionNum++;
+        }
+        // cell-component 가 있으면 cell.set() 으로 이미 갱신됨 (setSU/clearSU 안에서).
+        // 없으면 cellOverrides fallback 적용.
+        if (!hasCells) {
+            this.setState({ cellOverrides: next });
+        }
+        else {
+            this.invalidateLocationIndex();
+        }
     }
-    oncellchanged(after, before) {
-        this.invalidate();
+    /**
+     * 모든 grid 위치 (전체 columns × rows) 의 posKey 목록.
+     */
+    _allPosKeys() {
+        const cols = this.columns;
+        const rows = this.rackRows;
+        const out = [];
+        for (let r = 0; r < rows; r++) {
+            for (let c = 0; c < cols; c++) {
+                out.push(`${c}-${r}`);
+            }
+        }
+        return out;
+    }
+    /**
+     * Row 의 col 순회 순서 결정. boustrophedon (S 자형) 패턴 지원.
+     *   cw   : 짝수 row 는 좌→우, 홀수 row 는 우→좌
+     *   ccw  : 짝수 row 는 우→좌, 홀수 row 는 좌→우
+     *   zigzag         : 모든 row 좌→우 (단순)
+     *   zigzag-reverse : 모든 row 우→좌
+     */
+    _orderCols(row, sectionRows, direction, maxCol) {
+        // section 내 row 의 *상대 인덱스* — section 경계에서 패턴이 리셋되도록.
+        const idxInSection = sectionRows.indexOf(row);
+        const cols = [];
+        for (let c = 0; c <= maxCol; c++)
+            cols.push(c);
+        switch (direction) {
+            case 'cw':
+                return idxInSection % 2 === 0 ? cols : cols.slice().reverse();
+            case 'ccw':
+                return idxInSection % 2 === 0 ? cols.slice().reverse() : cols;
+            case 'zigzag':
+                return cols;
+            case 'zigzag-reverse':
+                return cols.slice().reverse();
+        }
     }
 };
 RackGrid = __decorate([
     sceneComponent('rack-grid')
 ], RackGrid);
 export default RackGrid;
-;
-['rows', 'columns', 'widths', 'heights', 'widths_sum', 'heights_sum', 'controls'].forEach(getter => Component.memoize(RackGrid.prototype, getter, false));
 //# sourceMappingURL=rack-grid.js.map