@operato/scene-storage 10.0.0-beta.41 → 10.0.0-beta.43

package/src/rack-grid.ts

@@ -1,264 +1,105 @@
 /*
  * 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 {
-  ApplicationContext,
-  Component,
-  ComponentNature,
-  ContainerAbstract,
-  Control,
-  Layout,
-  Model,
-  POINT,
-  Properties,
-  sceneComponent,
-  RealObject
+  ApplicationContext, Component, ComponentNature, ContainerAbstract, Control, Layout,
+  Model, POINT, Properties, RealObject, sceneComponent
 } from '@hatiolab/things-scene'
 import type { State } from '@hatiolab/things-scene'
 import * as THREE from 'three'
-
-/** RackGrid 컴포넌트 state */
-export interface RackGridState extends State {
-  rows?: number
-  columns?: number
-  zone?: string
-  shelves?: number
-  locPattern?: string
-  sectionDigits?: number
-  unitDigits?: number
-  shelfLocations?: string
-  stockScale?: number
-  hideRackFrame?: boolean
-  legendTarget?: string
-  hideEmptyStock?: boolean
-  widths?: number[]
-  heights?: number[]
-}
-import { RackGridCell } from './rack-grid-cell.js'
+import {
+  Placeable,
+  SlotTarget,
+  type Alignment,
+  type Heights,
+  type PlacementArchetype,
+  type SlotRecord,
+  type SlottedHolder
+} from '@operato/scene-base'
+
+import StorageRack from './storage-rack.js'
+import RackGridCell from './rack-grid-cell.js'
 import { RackGrid3D } from './rack-grid-3d.js'
-import { increaseLocation } from './rack-grid-location.js'
-import type { StockMaterialProvider } from './stock.js'
-
-const NATURE: ComponentNature = {
-  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'
-}
-
-type SIDE_KEY = 'all' | 'out' | 'left' | 'right' | 'top' | 'bottom' | 'leftright' | 'topbottom'
-
-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']
-} as { [key: string]: SIDE_KEY[] }
-
-const CLEAR_STYLE = {
-  strokeStyle: '',
-  lineDash: 'solid',
-  lineWidth: 0
-}
 
-const DEFAULT_STYLE = {
-  strokeStyle: '#999',
-  lineDash: 'solid',
-  lineWidth: 1
+// RackGridCell 의 refid 충돌 회피 — load 시 동적 생성되는 cell 의 refid 가 *부모
+// RackGrid + 모델 안 다른 컴포넌트* refid 와 겹치지 않도록 *높은 시작값 + monotonic
+// counter*. hierarchy override 가 save 시 refid 제거 → 모델 파일엔 안 새겨짐.
+let _cellRefidCounter = 100_000_000
+function _nextCellRefid(): number {
+  return _cellRefidCounter++
 }
 
-const TABLE_LAYOUT = Layout.get('table')
-
 function buildNewCell(app: ApplicationContext) {
-  return Model.compile(
+  const refid = _nextCellRefid()
+  const m: any = 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
   )
+  // 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)
+    }
+  } catch {}
+  return m
 }
 
-function buildCopiedCell(copy: any, app: ApplicationContext) {
-  const obj = JSON.parse(JSON.stringify(copy))
-  delete obj.text
-
-  return Model.compile(obj, app)
-}
-
-function buildBorderStyle(style: any, where: SIDE_KEY): { [key: string]: any } {
-  return (SIDES[where] || []).reduce((border: { [key: string]: any }, side: string) => {
-    border[side] = style
-    return border
-  }, {} as { [key: string]: any })
-}
-
-function setCellBorder(cell: RackGridCell, style: any, where: SIDE_KEY) {
-  if (!cell) {
-    return
-  }
-
-  cell.set('border', Object.assign({}, cell.getState('border') || {}, buildBorderStyle(style, where)))
-}
-
-function isLeftMost(total: number, columns: number, indices: number[], i: number) {
-  return i == 0 || !(i % columns) || indices.indexOf(i - 1) == -1
-}
-
-function isRightMost(total: number, columns: number, indices: number[], i: number) {
-  return i == total - 1 || i % columns == columns - 1 || indices.indexOf(i + 1) == -1
-}
-
-function isTopMost(total: number, columns: number, indices: number[], i: number) {
-  return i < columns || indices.indexOf(i - columns) == -1
-}
-
-function isBottomMost(total: number, columns: number, indices: number[], i: number) {
-  return i > total - columns - 1 || indices.indexOf(i + columns) == -1
-}
-
-function above(columns: number, i: number) {
-  return i - columns
-}
-
-function below(columns: number, i: number) {
-  return i + columns
-}
-
-function before(columns: number, i: number) {
-  return !(i % columns) ? -1 : i - 1
-}
-
-function after(columns: number, i: number) {
-  return !((i + 1) % columns) ? -1 : i + 1
-}
+const TABLE_LAYOUT = Layout.get('table')
 
-function array(value: any, size: number) {
-  const arr = []
-  for (let i = 0; i < size; i++) arr.push(1)
+function arrayOf(value: number, size: number): number[] {
+  const arr: number[] = []
+  for (let i = 0; i < size; i++) arr.push(value)
   return arr
 }
 
 const columnControlHandler = {
-  ondragmove: function (point: POINT, index: number, component: RackGrid) {
+  ondragmove(point: POINT, index: number, component: RackGrid) {
     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: number, width: number) => 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 diff_unit = Math.min(widths[index + 1] - min_width_unit, diff_unit)
@@ -271,29 +112,20 @@ const columnControlHandler = {
 }
 
 const rowControlHandler = {
-  ondragmove: function (point: POINT, index: number, component: RackGrid) {
+  ondragmove(point: POINT, index: number, component: RackGrid) {
     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: number, height: number) => 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 diff_unit = Math.min(heights[index + 1] - min_height_unit, diff_unit)
@@ -305,690 +137,1359 @@ const rowControlHandler = {
   }
 }
 
-@sceneComponent('rack-grid')
-export default class RackGrid extends ContainerAbstract implements StockMaterialProvider {
-  override get state(): RackGridState {
-    return super.state as RackGridState
-  }
+// ─── Cell-level metadata (sparse override) ────────────────────────────────────
+
+/** 한 (col, row) 위치의 메타데이터. 명시되지 않은 위치는 *룰의 기본값* 적용 (= location 없음). */
+export interface CellOverride {
+  /** Location 의 `{s}` 부분. unit 과 함께 명시되어야 location 부여됨. */
+  section?: string
+  /** Location 의 `{u}` 부분. section 과 함께 명시되어야 location 부여됨. */
+  unit?: string
+  /**
+   * 명시적 통로/공실 표시. 의미:
+   *   - location 미부여 (이 cell 로는 외부 location key 매칭 불가)
+   *   - increaseLocation 의 aisle row 로 인식 (skipNumbering 시 건너뜀)
+   * 자식 컴포넌트 종류는 무관 — Crane/AGV/forklift/비움 모두 OK.
+   */
+  isEmpty?: boolean
+  /** 4-side border style (top/left/bottom/right) — modeling 시각 용. */
+  border?: any
+  /** Grid merge — 시각 표현. */
+  merged?: boolean
+  rowspan?: number
+  colspan?: number
+}
 
-  _focused_cell?: RackGridCell
+// ─── State ────────────────────────────────────────────────────────────────────
 
-  // StockMaterialProvider 구현
-  _stock_materials: THREE.Material[] = []
-  _default_material?: THREE.Material
-  _empty_material?: THREE.Material
-  private _legendTarget?: Component
+export interface RackGridState extends State {
+  /** Grid 가로 칸 수 (X 축). 각 칸 ≈ 1 column 의 StorageRack (또는 Crane 등). */
+  columns?: number
+  /** Grid 세로 칸 수 (Z 축, depth). 통상 1, double-deep rack 등은 2. */
+  rows?: number
+  /** 각 (col, row) 의 수직 shelf 수 (Y 축, level). 자식 StorageRack 의 levels 와 일치. */
+  shelves?: number
 
-  get legendTarget(): Component | undefined {
-    const { legendTarget } = this.state
+  /**
+   * 첫 shelf 의 시작 높이 (mm, 3D Y 축, 바닥부터). 미명시 0 (바닥 = 첫 shelf).
+   * 양수 시 그만큼 위로 올라가 *stocker port / conveyor 같은 컴포넌트가 들어갈 빈 공간*
+   * 확보. Frame uprights 는 바닥 ~ 천장 그대로.
+   */
+  shelfBaseHeight?: number
+
+  // ── Location 룰 (rack-table 컨벤션) ──
+  zone?: string
+  /** 기본 `'{z}{s}-{u}-{sh}'`. placeholders: {z} {s} {u} {sh}. */
+  locPattern?: string
+  /** Section 숫자 자리수 (zero-pad). 기본 2. */
+  sectionDigits?: number
+  /** Unit 숫자 자리수 (zero-pad). 기본 2. */
+  unitDigits?: number
+  /** Shelf label CSV. 예: '1,2,3' / ',,,04'. 빈 자리는 1-based 인덱스 default. */
+  shelfLocations?: string
+
+  /** Sparse cell metadata. key = posKey = `${col-1}-${row-1}` (0-based, 2 segments). */
+  cellOverrides?: { [posKey: string]: CellOverride }
+
+  /**
+   * Stock records — `{ cellId: 'col-row-shelf', type, ... }`. cellId 가 RackGrid 의
+   * cell 위치 (3 segments) 와 매칭되는 record 만 InstancedMesh instance 로 렌더링.
+   * Plan A 정신 — sparse 데이터, 자식 컴포넌트 없이 batched 시각화.
+   */
+  data?: Array<{ cellId: string; [key: string]: any }>
+
+  /**
+   * Popup 컴포넌트 id — 클릭 시 그 popup 을 invoke (anchor = 클릭된 cell 의 SlotTarget).
+   * 미명시 시 click event (`rack-grid-cell-click`) 만 emit.
+   */
+  popupRef?: string
+
+  // ── 시각화 옵션 ──
+  hideRackFrame?: boolean              // post + beam 모두 숨김
+  hideHorizontalFrame?: boolean        // 가로 frame (beam) 만 숨김 (post 유지)
+  legendTarget?: string
+  hideEmptyStock?: boolean
+  widths?: number[]
+  heights?: number[]
+}
+
+// ─── Nature ───────────────────────────────────────────────────────────────────
+//
+// `nature` 는 *static const* 가 아니라 *get nature()* — properties 의 widget event
+// handler 안 `this` 가 *해당 RackGrid 인스턴스* 를 가리키도록 (화살표 함수가
+// getter 의 `this` 를 capture). rack-table-cell 의 동일 패턴.
 
-    if (!this._legendTarget && legendTarget) {
-      this._legendTarget = this.root.findById?.(legendTarget)
-      this._legendTarget?.on('change', this._onLegendChanged, this)
+// ─── RackGrid ─────────────────────────────────────────────────────────────────
+
+@sceneComponent('rack-grid')
+export default class RackGrid
+  extends Placeable(ContainerAbstract)
+  implements SlottedHolder
+{
+  declare state: RackGridState
+
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (h: Heights) => h.ceiling - h.floor
+
+  get nature(): ComponentNature {
+    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: CustomEvent) => {
+                const { increasingDirection, skipNumbering, startSection, startUnit } = event.detail
+                const selected = (this.root as any)?.selected as RackGridCell[] | undefined
+                const keys = (selected || [])
+                  .filter(c => (c as any)?.state?.type === 'rack-grid-cell')
+                  .map(c => c.state.cellId)
+                  .filter((k): k is string => !!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'
     }
+  }
 
-    // 하위호환: 자체 legendTarget이 없으면 부모(Visualizer)의 legendTarget 폴백
-    if (!this._legendTarget) {
-      let ancestor = this.parent as any
-      while (ancestor) {
-        if (ancestor.legendTarget) return ancestor.legendTarget
-        ancestor = ancestor.parent
-      }
-      // 서비스 레지스트리 폴백: stock-hub의 legendTarget
-      const stockHub = (this.root as any)?.getService?.('stock')
-      if (stockHub?.legendTarget) return stockHub.legendTarget
+  get anchors() {
+    return []
+  }
+
+  /**
+   * 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(): any {
+    const base: any = super.hierarchy
+    if (base?.components && Array.isArray(base.components)) {
+      base.components = base.components.map((c: any) => {
+        if (!c || typeof c !== 'object') return c
+        const { left, top, width, height, zPos, rotation, scale, translate, refid, ...rest } = c
+        return rest
+      })
     }
+    return base
+  }
 
-    return this._legendTarget
+  /** Focusible — children (RackGridCell) 도 editor 의 selection 가능 (rack-table 동일). */
+  get focusible() {
+    return false
   }
 
-  get hideEmptyStock(): boolean {
-    return !!this.getState('hideEmptyStock')
+  /** Lifecycle — children 자동 생성. columns × rows 만큼 RackGridCell 자식. */
+  created() {
+    const tobeSize = this.columns * this.rackRows
+    const gap = ((this as any).size?.() ?? this.components.length) - tobeSize
+
+    if (gap === 0) {
+      // 자식 수는 맞음 — cellId 만 sync
+      this._syncChildCellIds()
+      return
+    } else if (gap > 0) {
+      ;(this as any).remove?.(this.components.slice(gap))
+    } else {
+      const newbies: any[] = []
+      for (let i = 0; i < -gap; i++) newbies.push(buildNewCell((this as any).app))
+      ;(this as any).add?.(newbies)
+    }
+
+    const widths = this.getState('widths')
+    const heights = this.getState('heights')
+    if (!widths || (widths as number[]).length < this.columns) this.set('widths', this.widths)
+    if (!heights || (heights as number[]).length < this.rackRows) this.set('heights', this.heights)
+
+    this._syncChildCellIds()
   }
 
-  private _onLegendChanged() {
-    this._resetMaterials()
-    this.invalidate()
+  /** columns/rows 변경 시 children 재구성. rack-table.buildCells 패턴. */
+  onchange(after: Properties, _before: Properties) {
+    super.onchange?.(after, _before)
+    if ('columns' in after || 'rows' in after) {
+      const oldCols = (_before as any).columns ?? this.columns
+      const oldRows = (_before as any).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 as any)?.rebuildStockMesh?.()
+    }
+    // hideRackFrame / hideHorizontalFrame 변경 → frame visibility 즉시 토글
+    if ('hideRackFrame' in after || 'hideHorizontalFrame' in after) {
+      ;(this._realObject as any)?.applyFrameVisibility?.()
+    }
   }
 
-  private _resetMaterials() {
-    this._stock_materials.forEach(m => m.dispose?.())
-    this._stock_materials = []
-    delete this._default_material
-    delete this._empty_material
+  /** state.data 변경 시 호출 (things-scene 의 onchange<PropName>). */
+  onchangeData(): void {
+    ;(this._realObject as any)?.rebuildStockMesh?.()
   }
-  buildRealObject(): RealObject | undefined {
-    return new RackGrid3D(this)
+
+  /** state.data 의 records — Plan A 의 stock 보관소. */
+  get records(): Array<{ cellId: string; [key: string]: any }> {
+    return (this.state.data as any) ?? []
   }
 
-  dispose() {
-    this._legendTarget?.off('change', this._onLegendChanged, this)
-    delete this._legendTarget
-    this._resetMaterials()
+  // ── Legend integration ──────────────────────────────────
+
+  private _legendTarget?: Component
 
-    super.dispose()
+  /**
+   * Legend 컴포넌트 lookup. 우선순위:
+   *   1) state.legendTarget id 명시
+   *   2) scene 전체 의 type='legend' 첫 번째 컴포넌트 (자동 발견)
+   */
+  get legendTarget(): Component | undefined {
+    if (this._legendTarget) return this._legendTarget
+
+    const id = this.state.legendTarget
+    if (id) {
+      const found = (this.root as any)?.findById?.(id) as Component | undefined
+      if (found) {
+        this._legendTarget = found
+        ;(found as any).on?.('change', this._onLegendChanged, this)
+        return found
+      }
+    }
 
-    delete this._focused_cell
+    const visit = (node: any): Component | undefined => {
+      if (!node) return undefined
+      if (node.state?.type === 'legend') return node as Component
+      const children = node.components as Component[] | undefined
+      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 as any).on?.('change', this._onLegendChanged, this)
+    }
+    return found
   }
 
-  created() {
-    const tobeSize = this.rows * this.columns
-    const gap = this.size() - tobeSize
+  private _onLegendChanged = (): void => {
+    ;(this._realObject as any)?.rebuildStockMesh?.()
+  }
 
-    if (gap == 0) {
-      return
-    } else if (gap > 0) {
-      let removals = this.components.slice(gap)
-      this.remove(removals)
-    } else {
-      let newbies = []
+  /**
+   * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+   *   - `range.value === recordValue` (카테고리 일치)
+   *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+   *   - 매칭 없으면 `defaultColor` 또는 undefined
+   */
+  // ── View-mode click → rack-grid-cell-click event + popup ──
 
-      for (let i = 0; i < -gap; i++) newbies.push(buildNewCell(this.app))
+  get eventMap() {
+    return {
+      '(self)': {
+        '(self)': {
+          click: this._onViewClick
+        }
+      }
+    }
+  }
 
-      this.add(newbies)
+  private _onViewClick = (mouseEvent: MouseEvent) => {
+    if (!(this as any).app?.isViewMode) return
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return
+
+    const hit = this._raycastHit(mouseEvent)
+    if (!hit) return
+
+    const stockMesh: THREE.InstancedMesh | undefined = ro.stockMesh
+    let cellId: string | undefined
+    let record: any
+    let isStock = false
+    let instanceId: number | undefined
+
+    if (hit.object === stockMesh) {
+      const records: any[] | undefined = (stockMesh as any).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 as Array<any> | undefined
+      record = Array.isArray(data) ? data.find(r => r?.cellId === cid) : undefined
     }
 
-    const widths = this.getState('widths')
-    const heights = this.getState('heights')
+    const payload = { cellId, record, hitPoint: hit.point, instanceId, isStock }
+    this.trigger('rack-grid-cell-click', payload)
+    this._invokePopup(cellId, record)
 
-    if (!widths || widths.length < this.columns) this.set('widths', this.widths)
-    if (!heights || heights.length < this.rows) this.set('heights', this.heights)
+    // popup 외부 click 으로 인식되어 자동 close 되는 회귀 차단
+    mouseEvent.stopPropagation?.()
   }
 
-  // 컴포넌트를 임의로 추가 및 삭제할 수 있는 지를 지정하는 속성임.
-  get focusible() {
-    return false
+  /** state.popupRef Popup 컴포넌트 invoke. anchor = 클릭된 cell 의 SlotTarget. */
+  private _invokePopup(cellId: string | undefined, record: any): void {
+    const popupRefId = this.state.popupRef
+    if (!popupRefId || !cellId) return
+    const popupComp: any = (this.root as any)?.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 })
   }
 
-  get widths(): number[] {
-    const widths = this.getState('widths')
+  /** raycast → 우리 RackGrid 의 어떤 mesh 가 closest hit 인지. */
+  private _raycastHit(mouseEvent: MouseEvent): THREE.Intersection | undefined {
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return undefined
+    const tc: any = ro.threeContainer
+    if (!tc) return undefined
+
+    const cap: any = tc._threeCapability ?? tc._capability
+    let intersects: THREE.Intersection[] | undefined
+    if (cap?.getObjectsByRaycast) {
+      intersects = cap.getObjectsByRaycast() as THREE.Intersection[] | undefined
+    }
 
-    if (!widths) return array(1, this.columns)
+    if (!intersects || intersects.length === 0) {
+      const scene = tc.scene3d as THREE.Scene | undefined
+      const renderer = tc.renderer3d as THREE.WebGLRenderer | undefined
+      const camera =
+        (tc.activeCamera3d as THREE.Camera | undefined) ??
+        (cap?.activeCamera as THREE.Camera | undefined) ??
+        (cap?.camera as THREE.Camera | undefined)
+      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
 
-    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)
+    const closest = intersects[0]
+    let obj: THREE.Object3D | null = closest.object
+    while (obj) {
+      if (obj.userData?.context === ro) return closest
+      obj = obj.parent
+    }
+    return undefined
+  }
 
-    return widths
+  /** world point → cellId (col-row-shelf) 역산. */
+  private _cellIdFromWorldPoint(worldPoint: THREE.Vector3): string | null {
+    const ro: any = (this as any)._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 as number) || 1000
+    const height = (this.state.depth as number) || 2000   // 3D Y
+    const depth = (this.state.height as number) || 200    // 3D Z
+    const shelfBase = (this.state.shelfBaseHeight as number) || 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}`
   }
 
-  get heights(): number[] {
-    const heights = this.getState('heights')
+  resolveLegendColor(record: any): string | undefined {
+    const legend = this.legendTarget
+    if (!legend) return undefined
+    const status: any = (legend as any).getState?.('status') ?? (legend.state as any)?.status
+    if (!status) return undefined
 
-    if (!heights) return array(1, this.rows)
+    const field = status.field as string | undefined
+    const ranges = status.ranges as any[] | undefined
+    if (!field || !Array.isArray(ranges)) return undefined
 
-    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)
+    const value = record?.[field]
+    if (value === undefined || value === null) return status.defaultColor
 
-    return heights
+    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 as string | undefined
   }
 
-  buildCells(newrows: number, newcolumns: number, oldrows: number, oldcolumns: number) {
+  /**
+   * 새 (rows × columns) 에 맞춰 children 재구성. rack-table.buildCells 정확 클론.
+   */
+  private _buildCells(newrows: number, newcolumns: number, oldrows: number, oldcolumns: number) {
+    const app = (this as any).app
     if (newrows < oldrows) {
-      let removals = this.components.slice(oldcolumns * newrows)
-      this.remove(removals)
+      const removals = this.components.slice(oldcolumns * newrows)
+      ;(this as any).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 as any).insertComponentAt?.(buildNewCell(app), r * newcolumns + c)
         }
       }
     } else if (newcolumns < oldcolumns) {
-      let removals = []
-
+      const removals: any[] = []
       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 as any).remove?.(removals)
     }
-
     if (newrows > oldrows) {
-      let newbies = []
-
+      const newbies: any[] = []
       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 as any).add?.(newbies)
     }
+    this.set({ widths: this.widths, heights: this.heights })
+    this._syncChildCellIds()
+  }
 
-    this.set({
-      widths: this.widths,
-      heights: this.heights
-    })
+  /** children 의 state.cellId 가 *순서 기반 bayKey* 와 일치하도록 동기화. */
+  private _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: any = children[i]
+      if (c?.state?.cellId !== bayKey) c?.set?.('cellId', bayKey)
+    }
   }
 
-  get layout(): any {
-    return TABLE_LAYOUT
+  /** Row 인덱스의 cell 들. rack-table-cell 의 rowCells 가 사용. */
+  getCellsByRow(row: number): Component[] {
+    return this.components.slice(row * this.columns, (row + 1) * this.columns)
+  }
+  /** Column 인덱스의 cell 들. */
+  getCellsByColumn(column: number): Component[] {
+    const out: Component[] = []
+    for (let i = 0; i < this.rackRows; i++) out.push(this.components[this.columns * i + column])
+    return out
   }
 
-  get rows() {
-    return this.getState('rows')
+  /** (col, row) 위치의 cell-component. */
+  cellAt(col: number, row: number = 0): RackGridCell | null {
+    const idx = row * this.columns + col
+    return (this.components[idx] as any) ?? null
   }
 
-  setCellsStyle(cells: RackGridCell[], style: any, where: string) {
-    const components = this.components
-    const total = components.length
-    const columns = this.getState('columns')
+  /** bayKey 의 cell-component. */
+  cellAtBayKey(bayKey: string): RackGridCell | null {
+    const parsed = this.parsePosKey(bayKey)
+    if (!parsed) return null
+    return this.cellAt(parsed.col, parsed.row)
+  }
 
-    // 병합된 셀도 포함시킨다.
-    const _cells = [] as RackGridCell[]
-    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] as RackGridCell)
-      }
-    })
+  /**
+   * (col, row) bay 가 *isEmpty* 인가. cell-component 의 state.isEmpty 가 source of
+   * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
+   */
+  isBayEmpty(col: number, row: number = 0): boolean {
+    const cell = this.cellAt(col, row)
+    if (cell) return !!cell.state.isEmpty
+    const posKey = `${col}-${row}`
+    return !!this.cellOverrides[posKey]?.isEmpty
+  }
 
-    const indices = _cells.map(cell => components.indexOf(cell))
-    indices.forEach(i => {
-      const cell = components[i] as RackGridCell
-
-      switch (where) {
-        case 'all':
-          setCellBorder(cell, style, where)
-
-          if (isLeftMost(total, columns, indices, i))
-            setCellBorder(components[before(columns, i)] as RackGridCell, style, 'right')
-          if (isRightMost(total, columns, indices, i))
-            setCellBorder(components[after(columns, i)] as RackGridCell, style, 'left')
-          if (isTopMost(total, columns, indices, i))
-            setCellBorder(components[above(columns, i)] as RackGridCell, style, 'bottom')
-          if (isBottomMost(total, columns, indices, i))
-            setCellBorder(components[below(columns, i)] as RackGridCell, 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)] as RackGridCell, style, 'right')
-          }
-          if (isRightMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'right')
-            setCellBorder(components[after(columns, i)] as RackGridCell, style, 'left')
-          }
-          if (isTopMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'top')
-            setCellBorder(components[above(columns, i)] as RackGridCell, style, 'bottom')
-          }
-          if (isBottomMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'bottom')
-            setCellBorder(components[below(columns, i)] as RackGridCell, style, 'top')
-          }
-          break
-        case 'left':
-          if (isLeftMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'left')
-            setCellBorder(components[before(columns, i)] as RackGridCell, style, 'right')
-          }
-          break
-        case 'right':
-          if (isRightMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'right')
-            setCellBorder(components[after(columns, i)] as RackGridCell, 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)] as RackGridCell, style, 'bottom')
-          }
-          break
-        case 'bottom':
-          if (isBottomMost(total, columns, indices, i)) {
-            setCellBorder(cell, style, 'bottom')
-            setCellBorder(components[below(columns, i)] as RackGridCell, style, 'top')
-          }
-          break
-        case 'clear':
-          setCellBorder(cell, CLEAR_STYLE, 'all')
-
-          if (isLeftMost(total, columns, indices, i))
-            setCellBorder(components[before(columns, i)] as RackGridCell, CLEAR_STYLE, 'right')
-          if (isRightMost(total, columns, indices, i))
-            setCellBorder(components[after(columns, i)] as RackGridCell, CLEAR_STYLE, 'left')
-          if (isTopMost(total, columns, indices, i))
-            setCellBorder(components[above(columns, i)] as RackGridCell, CLEAR_STYLE, 'bottom')
-          if (isBottomMost(total, columns, indices, i))
-            setCellBorder(components[below(columns, i)] as RackGridCell, CLEAR_STYLE, 'top')
-      }
-    })
+  buildRealObject(): RealObject | undefined {
+    return new RackGrid3D(this)
   }
 
-  getRowColumn(cell: RackGridCell) {
-    const idx = this.components.indexOf(cell)
+  // ── Table layout — 자식 자동 배치 + columns/rows 의 가변 widths/heights ──
 
-    return {
-      column: idx % this.columns,
-      row: Math.floor(idx / this.columns)
-    }
+  get layout(): any {
+    return TABLE_LAYOUT
   }
 
-  getCellsByRow(row: number) {
-    return this.components.slice(row * this.columns, (row + 1) * this.columns)
+  get widths(): number[] {
+    const widths = this.getState('widths') as number[] | undefined
+    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
   }
 
-  getCellsByColumn(column: number) {
-    const cells = []
-    for (let i = 0; i < this.rows; i++) cells.push(this.components[this.columns * i + column])
-
-    return cells
+  get heights(): number[] {
+    const heights = this.getState('heights') as number[] | undefined
+    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
   }
 
-  deleteRows(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 행을 구한다.
-    let rows = [] as number[]
+  get widths_sum(): number {
+    return this.widths.reduce((sum, w) => sum + w, 0) || this.columns
+  }
 
-    cells.forEach(cell => {
-      let row = this.getRowColumn(cell).row
-      if (-1 == rows.indexOf(row)) {
-        rows.push(row)
-      }
-    })
+  get heights_sum(): number {
+    return this.heights.reduce((sum, h) => sum + h, 0) || this.rackRows
+  }
 
-    rows.sort((a, b) => {
-      return a - b
-    })
+  /** Column / Row 사이 드래그 핸들 — editor 의 widths/heights 가변 조절. */
+  get controls(): Array<Control> | undefined {
+    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
 
-    rows.reverse()
+    const controls: Array<Control> = []
 
-    const heights = this.heights.slice()
-    rows.forEach(row => {
-      this.remove(this.getCellsByRow(row))
+    let x = inside.left
+    widths.slice(0, this.columns - 1).forEach(w => {
+      x += w * width_unit
+      controls.push({ x, y: inside.top, handler: columnControlHandler })
     })
 
-    rows.forEach(row => heights.splice(row, 1))
-
-    this.model.rows -= rows.length // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
-    this.set('heights', heights)
-  }
-
-  deleteColumns(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 열을 구한다.
-    let columns = [] as number[]
-    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)
+    let y = inside.top
+    heights.slice(0, this.rackRows - 1).forEach(h => {
+      y += h * height_unit
+      controls.push({ x: inside.left, y, handler: rowControlHandler })
     })
-  }
 
-  insertCellsAbove(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 행을 구한다.
-    let rows = [] as number[]
-    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 = [] as number[]
-    let newbieCells = [] as RackGridCell[]
-    rows.forEach(row => {
-      for (let i = 0; i < this.columns; i++)
-        newbieCells.push(buildCopiedCell(this.components[row * this.columns + i].model, this.app) as RackGridCell)
-
-      newbieRowHeights.push(this.heights[row])
-
-      newbieCells.reverse().forEach(cell => {
-        this.insertComponentAt(cell, insertionRowPosition * this.columns)
-      })
+    return controls
+  }
 
-      let heights = this.heights.slice()
-      heights.splice(insertionRowPosition, 0, ...newbieRowHeights)
-      this.set('heights', heights)
+  // ── 2D 렌더링 — table layout 의 widths/heights 기반 격자 ─────
+  //
+  // 자식 컴포넌트 가 자기 렌더링하지만 *비어있는 grid 도 modeling 시 가시화*. 격자
+  // 좌표는 widths/heights (table layout 의 가변 분할) 기반. cellOverrides 의
+  // isEmpty (사선) + border (4-side) 도 표시.
 
-      this.model.rows += rows.length
+  render(ctx: CanvasRenderingContext2D) {
+    // 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 as string) || '#e8e8ec'
+    const stroke = (this.state.strokeStyle as string) || '#888'
+    const lineWidth = (this.state.lineWidth as number) || 1
+    const overrides = this.cellOverrides
+
+    // column 별 X 좌표 (좌→우 누적)
+    const xs: number[] = [left]
+    for (let c = 0; c < cols; c++) xs.push(xs[c] + (widths[c] / wSum) * width)
+    // row 별 Y 좌표 (상→하 누적)
+    const ys: number[] = [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)
+    }
+    for (let r = 1; r < rows; r++) {
+      ctx.moveTo(left, ys[r]); ctx.lineTo(left + width, ys[r])
+    }
+    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: any, x1: number, y1: number, x2: number, y2: number) => {
+        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)
+    }
 
-      this.clearCache()
-    })
+    // Selected bay 강조는 *rack-grid-cell 자체* 의 render 가 처리 (framework 의
+    // selection 시스템이 cell 의 outline 자동 그림). RackGrid 는 grid 골격만.
   }
 
-  insertCellsBelow(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 행을 구한다.
-    let rows = [] as number[]
-    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 = [] as number[]
-    let newbieCells = [] as RackGridCell[]
-    rows.forEach(row => {
-      for (let i = 0; i < this.columns; i++)
-        newbieCells.push(buildCopiedCell(this.components[row * this.columns + i].model, this.app) as RackGridCell)
-      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)
+  // ── Grid layout ─────────────────────────────────────────
 
-      this.model.rows += 1
+  get columns(): number {
+    return Math.max(1, Math.floor(this.state.columns ?? 5))
+  }
 
-      this.clearCache()
-    })
+  get rackRows(): number {
+    return Math.max(1, Math.floor(this.state.rows ?? 1))
   }
 
-  insertCellsLeft(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 열을 구한다.
-    let columns = [] as number[]
-    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 = [] as number[]
-    let newbieCells = [] as RackGridCell[]
-    columns.forEach(column => {
-      for (let i = 0; i < this.rows; i++)
-        newbieCells.push(buildCopiedCell(this.components[column + this.columns * i].model, this.app) as RackGridCell)
-      newbieColumnWidths.push(this.widths[column])
-
-      let increasedColumns = this.columns
-      let index = this.rows
-      newbieCells.reverse().forEach(cell => {
-        if (index == 0) {
-          index = this.rows
-          increasedColumns++
-        }
+  get shelves(): number {
+    return Math.max(1, Math.floor(this.state.shelves ?? 4))
+  }
 
-        index--
-        this.insertComponentAt(cell, insertionColumnPosition + index * increasedColumns)
-      })
+  // ── cellId / posKey 변환 ────────────────────────────────
 
-      let widths = this.widths.slice()
-      this.model.columns += columns.length // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
+  /** posKey = `${col-1}-${row-1}` (0-based, 2 segments). 1-based input. */
+  posKeyOf(col: number, row: number = 1): string {
+    return `${col - 1}-${row - 1}`
+  }
 
-      widths.splice(insertionColumnPosition, 0, ...newbieColumnWidths)
+  /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
+  cellIdOf(col: number, row: number = 1, shelf: number = 1): string {
+    return `${col - 1}-${row - 1}-${shelf - 1}`
+  }
 
-      this.set('widths', widths)
-    })
+  parseCellId(cellId: string): { col: number; row: number; shelf: number } | null {
+    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 }
   }
 
-  insertCellsRight(cells: RackGridCell[]) {
-    // 먼저 cells 위치의 열을 구한다.
-    let columns = [] as number[]
-    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 = [] as number[]
-    let newbieCells = [] as RackGridCell[]
-    columns.forEach(column => {
-      for (let i = 0; i < this.rows; i++)
-        newbieCells.push(buildCopiedCell(this.components[column + this.columns * i].model, this.app) as RackGridCell)
-      newbieColumnWidths.push(this.widths[column])
-
-      let increasedColumns = this.columns
-      let index = this.rows
-      newbieCells.reverse().forEach(cell => {
-        if (index == 0) {
-          index = this.rows
-          increasedColumns++
-        }
+  parsePosKey(posKey: string): { col: number; row: number } | null {
+    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 }
+  }
 
-        index--
-        this.insertComponentAt(cell, insertionColumnPosition + index * increasedColumns)
-      })
+  // ── cellOverrides accessor ─────────────────────────────
 
-      let widths = this.widths.slice()
-      this.model.columns += columns.length // 고의적으로, change 이벤트가 발생하지 않도록 set(..)을 사용하지 않음.
+  get cellOverrides(): { [posKey: string]: CellOverride } {
+    return (this.state.cellOverrides ?? {}) as { [posKey: string]: CellOverride }
+  }
 
-      widths.splice(insertionColumnPosition, 0, ...newbieColumnWidths)
+  getCellOverride(posKey: string): CellOverride | undefined {
+    return this.cellOverrides[posKey]
+  }
 
-      this.set('widths', widths)
-    })
+  // ── 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(): string[] {
+    const input = this.state.shelfLocations
+    const levels = this.shelves
+    const parts = (input || '').split(',')
+    const out: string[] = []
+    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
   }
 
-  distributeHorizontal(cells: RackGridCell[]) {
-    const columns = [] as number[]
+  // ── Location 변환 (양방향) ──────────────────────────────
+
+  /**
+   * cellId → location string. 우선순위:
+   *   1. cell-component (state.section/unit) — source of truth
+   *   2. cellOverrides[posKey] — 호환성 fallback
+   * section/unit 둘 다 있고 isEmpty=false 일 때만 부여. 미부여 시 null.
+   */
+  locationOf(cellId: string): string | null {
+    const parsed = this.parseCellId(cellId)
+    if (!parsed) return null
+    const posKey = `${parsed.col}-${parsed.row}`
+
+    let section: string | undefined
+    let unit: string | undefined
+    let isEmpty: boolean | undefined
+    let cellShelfLocations: string | undefined
+
+    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
+    }
 
-    cells.forEach(cell => {
-      let rowcolumn = this.getRowColumn(cell)
+    if (!section || !unit || isEmpty) return null
 
-      if (-1 == columns.indexOf(rowcolumn.column)) columns.push(rowcolumn.column)
-    })
+    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)
 
-    const sum = columns.reduce((sum, column) => {
-      return sum + this.widths[column]
-    }, 0)
+    return pattern
+      .replace(/\{z\}/g, zone)
+      .replace(/\{s\}/g, section)
+      .replace(/\{u\}/g, unit)
+      .replace(/\{sh\}/g, shelfLabel)
+  }
 
-    const newval = Math.round((sum / columns.length) * 100) / 100
-    const widths = this.widths.slice()
-    columns.forEach(column => {
-      widths[column] = newval
-    })
+  /** cell.state.shelfLocations 명시 시 그것, 아니면 RackGrid 의 shelfLabels. */
+  private _shelfLabelsFromCell(cellShelfLocations: string | undefined): string[] {
+    const input = cellShelfLocations ?? this.state.shelfLocations
+    const levels = this.shelves
+    const parts = (input || '').split(',')
+    const out: string[] = []
+    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
+  }
 
-    this.set('widths', widths)
+  /** location string → cellId. sparse 역인덱스 lookup. 없으면 null. */
+  cellIdOfLocation(location: string): string | null {
+    return this._locationIndex.get(location) ?? null
   }
 
-  distributeVertical(cells: RackGridCell[]) {
-    const rows = [] as number[]
+  /** 모든 (override 명시된) cell 의 location 목록. inspection 용. */
+  get allLocations(): Array<{ cellId: string; location: string }> {
+    const result: Array<{ cellId: string; location: string }> = []
+    for (const [location, cellId] of this._locationIndex.entries()) {
+      result.push({ cellId, location })
+    }
+    return result
+  }
 
-    cells.forEach(cell => {
-      let rowcolumn = this.getRowColumn(cell)
+  // ── Location 역인덱스 (sparse cache) ────────────────────
+
+  private _locationIndexCache?: Map<string, string>
+
+  private get _locationIndex(): Map<string, string> {
+    if (this._locationIndexCache) return this._locationIndexCache
+    const map = new Map<string, string>()
+    const shelves = this.shelves
+
+    // 1. cell-component 들 (source of truth) — 모든 bay 순회
+    const cells = this.components as Component[] | undefined
+    if (cells && cells.length > 0) {
+      for (let i = 0; i < cells.length; i++) {
+        const cell: any = 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)
+        }
+      }
+    }
 
-      if (-1 == rows.indexOf(rowcolumn.row)) rows.push(rowcolumn.row)
-    })
+    // 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)
+        }
+      }
+    }
 
-    const sum = rows.reduce((sum, row) => {
-      return sum + this.heights[row]
-    }, 0)
+    this._locationIndexCache = map
+    return map
+  }
 
-    const newval = Math.round((sum / rows.length) * 100) / 100
-    const heights = this.heights.slice()
-    rows.forEach(row => {
-      heights[row] = newval
-    })
+  /** 룰 / cellOverrides 변경 시 호출. things-scene 의 onchange* 가 자동 호출. */
+  invalidateLocationIndex(): void {
+    this._locationIndexCache = undefined
+  }
 
-    this.set('heights', heights)
+  onchangeCellOverrides(): void { this.invalidateLocationIndex() }
+  onchangeLocPattern(): void { this.invalidateLocationIndex() }
+  onchangeShelfLocations(): void { this.invalidateLocationIndex() }
+  onchangeZone(): void { this.invalidateLocationIndex() }
+  onchangeSectionDigits(): void { this.invalidateLocationIndex() }
+  onchangeUnitDigits(): void { this.invalidateLocationIndex() }
+  onchangeShelves(): void { this.invalidateLocationIndex() }
+
+  // ── 자식 lookup ────────────────────────────────────────
+
+  /**
+   * (col, row) 위치의 자식 StorageRack. 자식이 StorageRack 이 아닌 경우 (Crane, AGV 등)
+   * 는 null — Carrier 보관은 StorageRack 만.
+   *
+   * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
+   * 자식 추가 시 자동 할당 또는 사용자가 명시.
+   */
+  private _childRackAt(posKey: string): StorageRack | null {
+    const parsed = this.parsePosKey(posKey)
+    if (!parsed) return null
+    const children = (this.components as Component[] | undefined) ?? []
+    for (const c of children) {
+      const type = (c.state as any)?.type
+      if (type !== 'storage-rack') continue
+      const childCol = ((c.state as any)?.column ?? 1) - 1
+      const childRow = ((c.state as any)?.row ?? 1) - 1
+      if (childCol === parsed.col && childRow === parsed.row) {
+        return c as unknown as StorageRack
+      }
+    }
+    return null
   }
 
-  increaseLocation(type: string, skipNumbering: boolean, startSection: number, startUnit: number) {
-    const { sectionDigits = 2, unitDigits = 2 } = this.state
-    const selectedCells = this.root.selected as RackGridCell[]
+  // ── SlottedHolder 컨트랙 — 자식 StorageRack 으로 위임 ────
 
-    increaseLocation(selectedCells, type, skipNumbering, startSection, startUnit, sectionDigits, unitDigits)
+  hasCarrierAt(slotId: string): boolean {
+    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
   }
 
-  get columns() {
-    return this.getState('columns')
+  obtainCarrier(slotIdOrLocation: string): Component | null {
+    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
   }
 
-  get lefts() {
-    return this.components.filter((c: any, i: any) => {
-      return !(i % this.columns)
-    })
+  canReceiveAt(slotIdOrLocation: string, carrier?: Component): boolean {
+    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
   }
 
-  get centers() {
-    return this.components.filter((c: any, i: any) => {
-      return i % this.columns && (i + 1) % this.columns
-    })
+  async receiveAt(slotIdOrLocation: string, carrier: Component, options?: any): Promise<void> {
+    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)
   }
 
-  get rights() {
-    return this.components.filter((c: any, i: any) => {
-      return !((i + 1) % this.columns)
-    })
+  recordFromCarrier(carrier: Component, slotId: string): SlotRecord {
+    const { id, refid, transform, ...rest } = ((carrier.state as any) || {}) as any
+    return { ...rest, cellId: slotId }
   }
 
-  get tops() {
-    return this.components.slice(0, this.columns)
-  }
+  /**
+   * Slot 의 attach object3d — Stock InstancedMesh 의 instance 와 *같은 world 위치* 에
+   * 위치한 invisible Object3D. popup tether / Carriable.applyHolderAttachPoint 가 이
+   * object3d 의 matrixWorld 를 사용. lazy 생성 + cache.
+   */
+  private _attachAnchorByCell: Map<string, THREE.Object3D> = new Map()
+
+  getSlotAttachObject3d(slotId: string): THREE.Object3D | undefined {
+    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: any = (this as any)._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)
+    }
 
-  get middles() {
-    return this.components.slice(this.columns, this.columns * (this.rows - 1))
+    // 위치 갱신 — Stock InstancedMesh 의 instance 위치 와 동일 공식
+    const rs: any = this.state
+    const cols = this.columns
+    const rows = this.rackRows
+    const shelves = this.shelves
+    const width = (rs?.width as number) ?? 400
+    const height = (rs?.depth as number) ?? 2000
+    const depth = (rs?.height as number) ?? 200
+    const shelfBase = Math.max(0, Math.min((rs?.shelfBaseHeight as number) || 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
   }
 
-  get bottoms() {
-    return this.components.slice(this.columns * (this.rows - 1))
+  getSlotSize(slotId: string): { width: number; height: number; depth: number } | undefined {
+    const parsed = this.parseCellId(slotId)
+    if (!parsed) return undefined
+    const rs: any = this.state
+    const width = (rs?.width as number) ?? 400
+    const height = (rs?.depth as number) ?? 2000
+    const depth = (rs?.height as number) ?? 200
+    const shelfBase = Math.max(0, Math.min((rs?.shelfBaseHeight as number) || 0, height * 0.9))
+    const shelfZone = height - shelfBase
+    const cellY = shelfZone / this.shelves
+    return {
+      width: (width / this.columns) * 0.85,
+      height: (depth / this.rackRows) * 0.85,    // 2D height = 3D Z 폭
+      depth: cellY * 0.7                          // 3D Y 폭 (= stockD)
+    }
   }
 
-  get all() {
-    return this.components
+  cellCenter2D(slotId: string): { x: number; y: number } | null {
+    const parsed = this.parseCellId(slotId)
+    if (!parsed) return null
+    const rs: any = this.state
+    const left = (rs?.left as number) ?? 0
+    const top = (rs?.top as number) ?? 0
+    const width = (rs?.width as number) ?? 400
+    const height = (rs?.height as number) ?? 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 }
   }
 
-  get widths_sum() {
-    const widths = this.widths
-    return widths ? widths.filter((width, i) => i < this.columns).reduce((sum, width) => sum + width, 0) : this.columns
+  slotTargetAt(slotIdOrLocation: string): SlotTarget {
+    const slotId = this._resolveToCellId(slotIdOrLocation)
+    if (!slotId) throw new Error(`RackGrid.slotTargetAt: cannot resolve "${slotIdOrLocation}"`)
+    return new SlotTarget(this, slotId)
   }
 
-  get heights_sum() {
-    const heights = this.heights
-    return heights ? heights.filter((height, i) => i < this.rows).reduce((sum, height) => sum + height, 0) : this.rows
+  // ── Helpers ──────────────────────────────────────────
+
+  /**
+   * 외부 입력 → 내부 cellId 변환:
+   *   - "N-N-N" (3 segments, 모두 숫자) → cellId 그대로 (dual-accept)
+   *   - 그 외 → location 으로 간주, locationIndex lookup
+   */
+  private _resolveToCellId(input: string): string | null {
+    if (this._isCellIdFormat(input)) return input
+    return this.cellIdOfLocation(input)
   }
 
-  get nature() {
-    return NATURE
+  private _isCellIdFormat(s: string): boolean {
+    const parts = s.split('-')
+    return parts.length === 3 && parts.every(p => /^\d+$/.test(p))
   }
 
-  get controls(): Array<Control> | undefined {
-    const widths = this.widths
-    const heights = this.heights
-    const inside = this.textBounds
+  // ── Bulk 편집 API ────────────────────────────────────────
+  //
+  // 모두 *single setState* 로 cellOverrides 갱신 → 단일 'change' 이벤트만 발사.
+  // 매핑 cascade 회피 위해 silent 갱신 메서드 제공 (`_setCellOverridesSilently`).
+
+  /**
+   * 한 위치의 cellOverride 를 갱신 (merge). 기존 필드는 유지, 새 필드만 덮어씀.
+   * `partial` 의 필드가 *undefined* 면 *그 필드 삭제* (override 키에서 제거).
+   */
+  setCellOverride(posKey: string, partial: Partial<CellOverride>): void {
+    const current = this.cellOverrides
+    const existing = current[posKey] ?? {}
+    const merged: any = { ...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 })
+  }
 
-    const width_unit = inside.width / this.widths_sum
-    const height_unit = inside.height / this.heights_sum
+  /** 한 위치의 override 전체 삭제. */
+  clearCellOverride(posKey: string): void {
+    const current = this.cellOverrides
+    if (!(posKey in current)) return
+    const next = { ...current }
+    delete next[posKey]
+    this.setState({ cellOverrides: next })
+  }
 
-    let x = inside.left
-    let y = inside.top
+  /**
+   * 여러 위치의 isEmpty 일괄 토글. cell-component 있으면 cell.set(), 없으면 cellOverrides.
+   */
+  setIsEmpty(posKeys: string[], isEmpty: boolean): void {
+    const hasCells = this.components.some((c: Component) => (c as any)?.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: any = { ...existing, isEmpty }
+      if (!isEmpty && !existing.section && !existing.unit && !existing.border && !existing.merged) {
+        delete next[posKey]
+      } else {
+        next[posKey] = merged
+      }
+    }
+    this.setState({ cellOverrides: next })
+  }
 
-    const controls: Array<Control> = []
+  /**
+   * 여러 위치의 border 스타일 일괄 설정. `where` ('top'|'left'|'bottom'|'right'|'all').
+   *   - style = null → 해당 side 삭제
+   *   - where = 'all' → 4면 모두 동일 style
+   */
+  setBorder(posKeys: string[], style: any, where: 'all' | 'top' | 'left' | 'bottom' | 'right' = 'all'): void {
+    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: any = { ...existing, border }
+      if (Object.keys(border).length === 0) delete merged.border
+      next[posKey] = merged
+    }
+    this.setState({ cellOverrides: next })
+  }
 
-    widths.slice(0, this.columns - 1).forEach((width: number) => {
-      x += width * width_unit
-      controls.push({
-        x: x,
-        y: inside.top,
-        handler: columnControlHandler
-      })
-    })
+  /**
+   * 자동 채번 — 선택된 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: string[],
+    direction: 'cw' | 'ccw' | 'zigzag' | 'zigzag-reverse' = 'cw',
+    skipNumbering: boolean = false,
+    startSection: number = 1,
+    startUnit: number = 1
+  ): void {
+    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: string[] = posKeys.length > 0
+      ? [...posKeys]
+      : this._allPosKeys()
+
+    // (1) row 별 분류 (2D 배열, [row][col] = posKey)
+    const byRow: (string | null)[][] = []
+    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
+    }
 
-    heights.slice(0, this.rows - 1).forEach((height: number) => {
-      y += height * height_unit
-      controls.push({
-        x: inside.left,
-        y: y,
-        handler: rowControlHandler
-      })
-    })
+    // (2) aisle row 식별 — row 의 모든 (선택된) cell 이 isEmpty
+    const overrides = this.cellOverrides
+    const isAisleRow = (row: number): boolean => {
+      const cells = byRow[row]
+      if (!cells || cells.length === 0) return true
+      return cells.every(p => p == null || overrides[p]?.isEmpty === true)
+    }
 
-    return controls
-  }
+    // (3) section 별 묶기 (aisle 사이의 연속 row 들)
+    const sections: number[][] = []
+    let currentSection: number[] = []
+    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: Component) => (c as any)?.state?.type === 'rack-grid-cell')
+    const next = { ...overrides }
+    let sectionNum = Number(startSection) || 1
+
+    const setSU = (posKey: string, section: number, unit: number) => {
+      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 }
+      }
+    }
 
-  onchange(after: Properties, before: Properties) {
-    if ('legendTarget' in after || 'legendTarget' in before) {
-      this._legendTarget?.off('change', this._onLegendChanged, this)
-      delete this._legendTarget
-      this._resetMaterials()
+    const clearSU = (posKey: string) => {
+      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
+      }
     }
 
-    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 (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++
     }
 
-    this.invalidate()
+    // cell-component 가 있으면 cell.set() 으로 이미 갱신됨 (setSU/clearSU 안에서).
+    // 없으면 cellOverrides fallback 적용.
+    if (!hasCells) {
+      this.setState({ cellOverrides: next })
+    } else {
+      this.invalidateLocationIndex()
+    }
   }
 
-  get eventMap() {
-    return {
-      '(self)': {
-        '(descendant)': {
-          change: this.oncellchanged
-        }
+  /**
+   * 모든 grid 위치 (전체 columns × rows) 의 posKey 목록.
+   */
+  private _allPosKeys(): string[] {
+    const cols = this.columns
+    const rows = this.rackRows
+    const out: string[] = []
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        out.push(`${c}-${r}`)
       }
     }
+    return out
   }
 
-  oncellchanged(after: Properties, before: Properties) {
-    this.invalidate()
+  /**
+   * Row 의 col 순회 순서 결정. boustrophedon (S 자형) 패턴 지원.
+   *   cw   : 짝수 row 는 좌→우, 홀수 row 는 우→좌
+   *   ccw  : 짝수 row 는 우→좌, 홀수 row 는 좌→우
+   *   zigzag         : 모든 row 좌→우 (단순)
+   *   zigzag-reverse : 모든 row 우→좌
+   */
+  private _orderCols(
+    row: number,
+    sectionRows: number[],
+    direction: 'cw' | 'ccw' | 'zigzag' | 'zigzag-reverse',
+    maxCol: number
+  ): number[] {
+    // section 내 row 의 *상대 인덱스* — section 경계에서 패턴이 리셋되도록.
+    const idxInSection = sectionRows.indexOf(row)
+    const cols: number[] = []
+    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()
+    }
   }
 }
-
-;['rows', 'columns', 'widths', 'heights', 'widths_sum', 'heights_sum', 'controls'].forEach(getter =>
-  Component.memoize(RackGrid.prototype, getter, false)
-)