@operato/scene-transport 10.0.0-beta.28 → 10.0.0-beta.31

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.0.0-beta.31](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.30...v10.0.0-beta.31) (2026-05-08)
+
+
+### :rocket: New Features
+
+* **conveyance+transport+manufacturing:** induct→sorter→chute 자세 보존 + AGV/Forklift pick 보완 ([28c2ed7](https://github.com/things-scene/operato-scene/commit/28c2ed7b64d87b27e72e8cbd36a48a5d26d6cf8a))
+* **transport,conveyance:** Phase F Step 4-6 — carryPolicy 명시적 선언 ([522e003](https://github.com/things-scene/operato-scene/commit/522e0035ddf9357fb385183d03a54609b9e20ee1))
+
+
+### :bug: Bug Fix
+
+* **transport/visualizer:** children → components — 잠재 버그 수정 (Phase C Round 4) ([8131166](https://github.com/things-scene/operato-scene/commit/813116650dd846becfbf4f9571893cff25f85e62))
+
+
+### :house: Code Refactoring
+
+* _realObject 캐스트 16개 제거 (Phase C Round 2 후속) ([8616c6c](https://github.com/things-scene/operato-scene/commit/8616c6c45e38a9bbcc244a77cee53479a756df85))
+* 39개 buildRealObject 캐스트 제거 (Phase D Round 4 후속) ([b86681c](https://github.com/things-scene/operato-scene/commit/b86681c07d7bf41cb93ade9855afb21902ed8186))
+* **mfg/transport/storage:** typed state Round 2 — 14개 컴포넌트 적용 ([f1765f6](https://github.com/things-scene/operato-scene/commit/f1765f62d12cf4c20ea26a2297e98069b9621a45))
+* 함수 인자 (this as any) 13개 제거 (Phase D Round 4 후속) ([b0a400c](https://github.com/things-scene/operato-scene/commit/b0a400c9716fdec22518cc6ad0bd1c1e69bda89d))
+
+
+
+## [10.0.0-beta.30](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.29...v10.0.0-beta.30) (2026-05-07)
+
+
+### :rocket: New Features
+
+* **conveyance:** InductStation + CrossBeltLine + Chute 3D 시뮬레이션 전면 개선 ([e729b9d](https://github.com/things-scene/operato-scene/commit/e729b9dbb736ce1f12a4de789738ec1e58bf1dbc))
+
+
+
 ## [10.0.0-beta.28](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.27...v10.0.0-beta.28) (2026-05-05)
 
 

package/dist/agv.d.ts

@@ -1,4 +1,5 @@
 import { Component, ComponentNature, RealObject } from '@hatiolab/things-scene';
+import type { SlotDef, State, Material3D } from '@hatiolab/things-scene';
 import { type Alignment, type CarrierAttachPoint, type Heights, type LegendBinding, type MoveOptions, type PlacementArchetype } from '@operato/scene-base';
 /**
  * Agv status — common to both payload and towing AGVs (kept narrow on purpose).
@@ -14,6 +15,13 @@ import { type Alignment, type CarrierAttachPoint, type Heights, type LegendBindi
  * invite drift.
  */
 export type AgvStatus = 'idle' | 'moving' | 'charging' | 'error';
+/** Agv 컴포넌트 state */
+export interface AgvState extends State {
+    status?: AgvStatus;
+    battery?: number;
+    speed?: number;
+    material3d?: Material3D;
+}
 declare const Base: typeof Component & {
     new (...args: any[]): Component & {
         isCarrierHolder: boolean;
@@ -37,6 +45,7 @@ declare const Base: typeof Component & {
  * For the towing variant (no cargo deck, pulls trailers behind), see Tugger.
  */
 export default class Agv extends Base {
+    get state(): AgvState;
     static legends: Record<string, LegendBinding>;
     /**
      * AGV sits on its wheels — `floor` archetype. Default depth = operation,
@@ -58,6 +67,11 @@ export default class Agv extends Base {
     static yawOffset: number;
     get nature(): ComponentNature;
     get anchors(): never[];
+    /**
+     * Single-cargo policy: AGV 는 한 번에 1개의 carrier 만 운반.
+     * 이미 1개를 보유한 상태에서는 `canReceive()` → false → `pick()` 거부.
+     */
+    get slots(): SlotDef[];
     /** Accept logistics packages (placement='operation') as deck cargo. */
     containable(component: Component): boolean;
     /**
@@ -76,6 +90,17 @@ export default class Agv extends Base {
      * children order is preserved; no persisted state needed.
      */
     private _slotIndexOf;
+    /**
+     * pick 보완: super.pick 후 carrier 의 자세 정렬 + attachPointFor 강제 재적용.
+     *
+     * 흐름의 마지막에 ContainerCapacity.receive 의 setState({left, top}) 가 표준
+     * pipeline 을 트리거해 obj3d.position 이 attachPointFor 의 localPosition 을 덮어씀.
+     * (= 첫번째 carrier 가 데크 위가 아니라 잘못된 위치/공중에 잡히는 원인)
+     * super.pick 종료 후 attachPointFor 를 다시 적용하고 suppressTransform=true 로
+     * pipeline 의 추가 override 차단. AGV 가 움직이면 carrier 는 scene-graph 통해 자동 추종.
+     */
+    pick(carrier: Component, options?: any): Promise<void>;
+    private _snapToAttachPoint;
     /**
      * 2D — render() sets up the rounded chassis path; the framework fills it
      * with `fillStyle` (= bodyColor from Legendable) and strokes with

package/dist/agv.js

@@ -2,7 +2,7 @@ import { __decorate } from "tslib";
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { ContainerAbstract, sceneComponent } from '@hatiolab/things-scene';
+import { ContainerAbstract, ContainerCapacity, sceneComponent } from '@hatiolab/things-scene';
 import { CarrierHolder, FloorBound, Legendable, Mover, Placeable } from '@operato/scene-base';
 import { Agv3D } from './agv-3d.js';
 /**
@@ -64,16 +64,19 @@ const NATURE = {
     ],
     help: 'scene/component/agv'
 };
-// Composition: ContainerAbstract → Placeable → Legendable → CarrierHolder → Mover → FloorBound.
-// Same chain as Forklift — the AGV is a wheeled, payload-carrying vehicle
-// with the same pick/place semantics; differences (deck-stack instead of
-// fork-mount) are encoded in `attachPointFor`. FloorBound is outermost so
-// its rotation guard sees state changes last.
+// Composition:
+//   FloorBound → Mover → CarrierHolder → ContainerCapacity → Legendable → Placeable → ContainerAbstract
 //
-// `ContainerAbstract` (not `Container`) — Container = MixinHTMLElement(ContainerAbstract),
-// which forces `isHTMLElement(): true` and trips the 3D pipeline's
-// addObject DOM-skip gate. AGV lives only in the 3D scene graph; no DOM.
-const Base = FloorBound(Mover(CarrierHolder(Legendable(Placeable(ContainerAbstract)))));
+//   ContainerCapacity: receive() / dispatch() / canReceive() / slots — Mover.pick uses
+//     receive() for slot-tracking and event emission on every cargo transfer.
+//   CarrierHolder:     attachPointFor() — deck-top 3D mount frame; Carriable.added()
+//     calls applyHolderAttachPoint() which uses our override for 3D positioning.
+//   Mover:             moveTo / pick / place / pickAndPlace / executeMission.
+//   FloorBound:        outermost rotation guard.
+//
+// `ContainerAbstract` (not `Container`) — avoids isHTMLElement()=true that would
+// trip the 3D pipeline's addObject DOM-skip gate.
+const Base = FloorBound(Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract))))));
 /**
  * Agv — payload (unit-load) automated guided vehicle. The Kiva-style flat-deck
  * AGV that drives under or carries cargo to/from operation surfaces.
@@ -87,6 +90,12 @@ const Base = FloorBound(Mover(CarrierHolder(Legendable(Placeable(ContainerAbstra
  * For the towing variant (no cargo deck, pulls trailers behind), see Tugger.
  */
 let Agv = class Agv extends Base {
+    // `Base` is cast through `typeof Component` so TS sees `state` as an
+    // accessor; `declare state: …` would conflict with TS2610. Override the
+    // getter instead — runtime behavior is identical (just delegates to super).
+    get state() {
+        return super.state;
+    }
     static legends = {
         bodyColor: { from: 'status', legend: BODY_LEGEND },
         lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
@@ -115,6 +124,14 @@ let Agv = class Agv extends Base {
     get anchors() {
         return [];
     }
+    // ── ContainerCapacity ─────────────────────────────────────────────────────
+    /**
+     * Single-cargo policy: AGV 는 한 번에 1개의 carrier 만 운반.
+     * 이미 1개를 보유한 상태에서는 `canReceive()` → false → `pick()` 거부.
+     */
+    get slots() {
+        return [{ id: 'deck', maxCount: 1 }];
+    }
     /** Accept logistics packages (placement='operation') as deck cargo. */
     containable(component) {
         const archetype = component.constructor.placement;
@@ -139,14 +156,19 @@ let Agv = class Agv extends Base {
         const depth = this.state.depth ?? 0;
         const slotIdx = this._slotIndexOf(carrier);
         const cargoDepth = carrier.state.depth ?? 100;
+        // 3D origin convention (beta.66+): carrier 의 origin = center.
+        // 데크 표면 (= AGV 상단) y = depth/2. carrier 의 bottom 을 데크 표면에 두려면
+        // carrier center y = deckY + cargoDepth/2. 이후 slot 별로 cargoDepth 씩 stack.
         const deckY = depth / 2;
         return {
             attach: ro.object3d,
             localPosition: {
                 x: 0,
-                y: deckY + slotIdx * cargoDepth,
+                y: deckY + cargoDepth / 2 + slotIdx * cargoDepth,
                 z: 0
-            }
+            },
+            // Phase F: AGV 가 회전하면 cargo 도 같이 회전 (deck 위 고정 lock).
+            carryPolicy: 'follow-holder'
         };
     }
     /**
@@ -154,10 +176,51 @@ let Agv = class Agv extends Base {
      * children order is preserved; no persisted state needed.
      */
     _slotIndexOf(carrier) {
-        const children = this.children ?? [];
+        const children = this.components ?? [];
         const idx = children.indexOf(carrier);
         return idx < 0 ? children.length : idx;
     }
+    /**
+     * pick 보완: super.pick 후 carrier 의 자세 정렬 + attachPointFor 강제 재적용.
+     *
+     * 흐름의 마지막에 ContainerCapacity.receive 의 setState({left, top}) 가 표준
+     * pipeline 을 트리거해 obj3d.position 이 attachPointFor 의 localPosition 을 덮어씀.
+     * (= 첫번째 carrier 가 데크 위가 아니라 잘못된 위치/공중에 잡히는 원인)
+     * super.pick 종료 후 attachPointFor 를 다시 적용하고 suppressTransform=true 로
+     * pipeline 의 추가 override 차단. AGV 가 움직이면 carrier 는 scene-graph 통해 자동 추종.
+     */
+    async pick(carrier, options = {}) {
+        // 1-capacity 정책: 이미 1개 보유 시 pick 거부 (moveTo / engage 낭비 방지).
+        if (!this.canReceive(carrier)) {
+            this.trigger('transfer-rejected', {
+                type: 'transfer-rejected',
+                component: carrier,
+                container: this,
+                reason: 'agv-at-capacity'
+            });
+            return;
+        }
+        await super.pick(carrier, options);
+        carrier.setState?.({ rotation: 0, rotationX: 0, rotationY: 0 });
+        this._snapToAttachPoint(carrier);
+    }
+    _snapToAttachPoint(carrier) {
+        const point = this.attachPointFor(carrier);
+        const ro = carrier._realObject;
+        const obj3d = ro?.object3d;
+        if (!obj3d || !point?.localPosition)
+            return;
+        const lp = point.localPosition;
+        obj3d.position.set(lp.x, lp.y, lp.z);
+        if (point.localRotation) {
+            obj3d.rotation.set(point.localRotation.x, point.localRotation.y, point.localRotation.z);
+        }
+        else {
+            obj3d.quaternion.identity();
+        }
+        if (ro)
+            ro.suppressTransform = true;
+    }
     /**
      * 2D — render() sets up the rounded chassis path; the framework fills it
      * with `fillStyle` (= bodyColor from Legendable) and strokes with

package/dist/agv.js.map

@@ -1 +1 @@
-{"version":3,"file":"agv.js","sourceRoot":"","sources":["../src/agv.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n */\nimport { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'\nimport {\n  CarrierHolder,\n  FloorBound,\n  Legendable,\n  Mover,\n  Placeable,\n  type Alignment,\n  type CarrierAttachPoint,\n  type Heights,\n  type LegendBinding,\n  type MoveOptions,\n  type PlacementArchetype\n} from '@operato/scene-base'\n\nimport { Agv3D } from './agv-3d.js'\n\n/**\n * Agv status — common to both payload and towing AGVs (kept narrow on purpose).\n *\n * - `idle`     — parked, awaiting task\n * - `moving`   — driving along a path / executing transport\n * - `charging` — at a charging dock / battery station\n * - `error`    — fault / blocked / e-stop\n *\n * Loaded-vs-empty distinction is *not* in the status enum because for a\n * Kiva-style payload AGV it's already obvious from the children (cargo\n * components) parented to it — duplicating that as a status flag would\n * invite drift.\n */\nexport type AgvStatus = 'idle' | 'moving' | 'charging' | 'error'\n\n/**\n * Body color — neutral industrial gray base, slightly modulated by status.\n * AGVs typically have status-color LED strips rather than full body color\n * change; the body legend stays subtle so the LED strip + lamp do the\n * communicating.\n */\nconst BODY_LEGEND = {\n  idle: '#999',\n  moving: '#aaa',\n  charging: '#aaa',\n  error: '#c66',\n  default: '#999'\n}\n\n/**\n * LED strip emissive — the dominant status indicator for AGVs (typically a\n * color-band running around the chassis perimeter).\n */\nconst LAMP_EMISSIVE_LEGEND = {\n  idle: '#222222',\n  moving: '#44ff44',  // green (operating)\n  charging: '#ffaa00', // amber (charging)\n  error: '#ff3333',   // red\n  default: '#222222'\n}\n\nconst NATURE: ComponentNature = {\n  mutable: false,\n  resizable: true,\n  rotatable: true,\n  properties: [\n    {\n      type: 'select',\n      label: 'status',\n      name: 'status',\n      property: {\n        options: [\n          { display: 'Idle', value: 'idle' },\n          { display: 'Moving', value: 'moving' },\n          { display: 'Charging', value: 'charging' },\n          { display: 'Error', value: 'error' }\n        ]\n      }\n    },\n    {\n      type: 'number',\n      label: 'battery',\n      name: 'battery',\n      placeholder: '0..1'\n    },\n    {\n      // AGV travel speed in scene units / second. Used by Mover.moveTo\n      // to derive motion duration. Tune per board scale; forklift convention.\n      type: 'number',\n      label: 'speed',\n      name: 'speed',\n      placeholder: 'units/sec'\n    }\n  ],\n  help: 'scene/component/agv'\n}\n\n// Composition: ContainerAbstract → Placeable → Legendable → CarrierHolder → Mover → FloorBound.\n// Same chain as Forklift — the AGV is a wheeled, payload-carrying vehicle\n// with the same pick/place semantics; differences (deck-stack instead of\n// fork-mount) are encoded in `attachPointFor`. FloorBound is outermost so\n// its rotation guard sees state changes last.\n//\n// `ContainerAbstract` (not `Container`) — Container = MixinHTMLElement(ContainerAbstract),\n// which forces `isHTMLElement(): true` and trips the 3D pipeline's\n// addObject DOM-skip gate. AGV lives only in the 3D scene graph; no DOM.\nconst Base = FloorBound(Mover(CarrierHolder(Legendable(Placeable(ContainerAbstract))))) as unknown as typeof Component & {\n  new (...args: any[]): Component & {\n    isCarrierHolder: boolean\n    isMover: boolean\n    attachPointFor(carrier: Component): CarrierAttachPoint | undefined\n    pick(carrier: Component, options?: MoveOptions): Promise<void>\n    place(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>\n    pickAndPlace(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>\n  }\n}\n\n/**\n * Agv — payload (unit-load) automated guided vehicle. The Kiva-style flat-deck\n * AGV that drives under or carries cargo to/from operation surfaces.\n *\n * **Container-based for cargo containment.** A payload Agv has a flat top\n * deck whose surface is at the scene's operation height. Boxes, parcels,\n * loaded pallets (anything with `placement: 'operation'`) can be added as\n * children — when they are, their natural archetype-derived zPos puts them\n * exactly on the AGV's deck (since AGV depth = operation - floor).\n *\n * For the towing variant (no cargo deck, pulls trailers behind), see Tugger.\n */\n@sceneComponent('agv')\nexport default class Agv extends Base {\n  static legends: Record<string, LegendBinding> = {\n    bodyColor: { from: 'status', legend: BODY_LEGEND },\n    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }\n  }\n\n  /**\n   * AGV sits on its wheels — `floor` archetype. Default depth = operation,\n   * so the top deck lands at the scene's operation height. This is the\n   * design point of payload AGVs: the deck height matches conveyor belt\n   * height, equipment ports, and forklift fork height — cargo transfers\n   * across all of them at the same level.\n   */\n  static placement: PlacementArchetype = 'floor'\n  static align: Alignment = 'bottom'\n  static defaultDepth = (h: Heights) => h.operation - h.floor\n\n  /**\n   * Heading yaw offset (rad). things-scene's vehicle convention is\n   * `vehicle forward = component-local -Z` (= \"rotation=0 → toward canvas\n   * top edge\"); the framework default `Math.PI / 2` aligns with that.\n   * Stated explicitly so the model's forward axis is documented at the\n   * class level rather than relying silently on the framework default.\n   */\n  static yawOffset = Math.PI / 2\n\n  get nature() {\n    return NATURE\n  }\n\n  get anchors() {\n    return []\n  }\n\n  /** Accept logistics packages (placement='operation') as deck cargo. */\n  containable(component: Component) {\n    const archetype = (component.constructor as any).placement\n    if (archetype === 'operation') return true\n    return component.isDescendible(this as any)\n  }\n\n  /**\n   * AGV attach point — flat top deck. Cargo lands on the deck surface\n   * (top of the AGV envelope, which is `+depth/2` in component-local Y).\n   * Multiple cargo items stack vertically by their own depth.\n   *\n   * `attach` is the AGV's `_realObject.object3d` directly — there is no\n   * inner sub-frame the way Forklift has a fork-tip frame, because the\n   * deck moves rigidly with the chassis. Cargo Y reflects the cargoDepth\n   * × slot index stack offset.\n   */\n  attachPointFor(carrier: Component): CarrierAttachPoint | undefined {\n    const ro = (this as any)._realObject as { object3d?: any } | undefined\n    if (!ro?.object3d) return undefined\n\n    const depth = (this.state.depth as number) ?? 0\n    const slotIdx = this._slotIndexOf(carrier)\n    const cargoDepth = (carrier.state as any).depth ?? 100\n    const deckY = depth / 2\n\n    return {\n      attach: ro.object3d,\n      localPosition: {\n        x: 0,\n        y: deckY + slotIdx * cargoDepth,\n        z: 0\n      }\n    }\n  }\n\n  /**\n   * Stack slot = the carrier's index among siblings. Stable because\n   * children order is preserved; no persisted state needed.\n   */\n  private _slotIndexOf(carrier: Component): number {\n    const children = ((this as any).children as Component[] | undefined) ?? []\n    const idx = children.indexOf(carrier)\n    return idx < 0 ? children.length : idx\n  }\n\n  /**\n   * 2D — render() sets up the rounded chassis path; the framework fills it\n   * with `fillStyle` (= bodyColor from Legendable) and strokes with\n   * `strokeStyle`. Additional top-down details (bumpers, LiDAR, lift pad,\n   * direction triangle) are drawn in `postrender()`.\n   */\n  render(ctx: CanvasRenderingContext2D) {\n    const { width, height, left, top } = this.state\n    const radius = Math.min(width, height) * 0.12\n    ctx.beginPath()\n    ctx.roundRect(left, top, width, height, radius)\n  }\n\n  /** Top-view accent details — bumpers, lift pad, LiDAR, direction triangle. */\n  postrender(ctx: CanvasRenderingContext2D) {\n    super.postrender?.(ctx)\n\n    const { width, height, left, top } = this.state\n    const cx = left + width / 2\n    const cy = top + height / 2\n    const accentColor = (this.state.lampEmissive as string) || '#44ff44'\n\n    ctx.save()\n\n    // Hi-vis bumper strips (front + rear)\n    const bumperT = Math.min(width, height) * 0.06\n    ctx.fillStyle = '#eeaa00'\n    ctx.fillRect(left + width * 0.15, top, width * 0.7, bumperT)\n    ctx.fillRect(left + width * 0.15, top + height - bumperT, width * 0.7, bumperT)\n    ctx.fillStyle = '#111'\n    ctx.fillRect(left + width * 0.02, top, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.85, top, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.02, top + height - bumperT, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.85, top + height - bumperT, width * 0.13, bumperT)\n\n    // Lift pad (center circle — Kiva-style under-shelf lift)\n    const padR = Math.min(width, height) * 0.22\n    ctx.fillStyle = '#4a4a55'\n    ctx.strokeStyle = '#222'\n    ctx.lineWidth = 1\n    ctx.beginPath()\n    ctx.ellipse(cx, cy, padR, padR, 0, 0, Math.PI * 2)\n    ctx.fill()\n    ctx.stroke()\n\n    // LiDAR sensor (small filled circle near front)\n    const lidarR = Math.min(width, height) * 0.07\n    ctx.fillStyle = '#222233'\n    ctx.beginPath()\n    ctx.ellipse(cx, top + height * 0.20, lidarR, lidarR, 0, 0, Math.PI * 2)\n    ctx.fill()\n    ctx.stroke()\n    // Status hint on LiDAR\n    ctx.fillStyle = accentColor\n    ctx.beginPath()\n    ctx.ellipse(cx, top + height * 0.20, lidarR * 0.4, lidarR * 0.4, 0, 0, Math.PI * 2)\n    ctx.fill()\n\n    // Direction-of-travel triangle\n    ctx.fillStyle = accentColor\n    ctx.strokeStyle = '#111'\n    ctx.beginPath()\n    ctx.moveTo(cx, top + height * 0.06)\n    ctx.lineTo(cx - width * 0.06, top + height * 0.13)\n    ctx.lineTo(cx + width * 0.06, top + height * 0.13)\n    ctx.closePath()\n    ctx.fill()\n    ctx.stroke()\n\n    ctx.restore()\n  }\n\n  buildRealObject(): RealObject | undefined {\n    return new Agv3D(this as any)\n  }\n}\n"]}
+{"version":3,"file":"agv.js","sourceRoot":"","sources":["../src/agv.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n */\nimport { Component, ComponentNature, ContainerAbstract, ContainerCapacity, RealObject, sceneComponent } from '@hatiolab/things-scene'\nimport type { SlotDef, State, Material3D } from '@hatiolab/things-scene'\nimport {\n  CarrierHolder,\n  FloorBound,\n  Legendable,\n  Mover,\n  Placeable,\n  type Alignment,\n  type CarrierAttachPoint,\n  type Heights,\n  type LegendBinding,\n  type MoveOptions,\n  type PlacementArchetype\n} from '@operato/scene-base'\n\nimport { Agv3D } from './agv-3d.js'\n\n/**\n * Agv status — common to both payload and towing AGVs (kept narrow on purpose).\n *\n * - `idle`     — parked, awaiting task\n * - `moving`   — driving along a path / executing transport\n * - `charging` — at a charging dock / battery station\n * - `error`    — fault / blocked / e-stop\n *\n * Loaded-vs-empty distinction is *not* in the status enum because for a\n * Kiva-style payload AGV it's already obvious from the children (cargo\n * components) parented to it — duplicating that as a status flag would\n * invite drift.\n */\nexport type AgvStatus = 'idle' | 'moving' | 'charging' | 'error'\n\n/** Agv 컴포넌트 state */\nexport interface AgvState extends State {\n  // ── 운영 상태 ──\n  status?: AgvStatus\n\n  // ── 시뮬레이션/모니터링 ──\n  battery?: number\n  speed?: number\n\n  // ── 3D 재질 ──\n  material3d?: Material3D\n}\n\n/**\n * Body color — neutral industrial gray base, slightly modulated by status.\n * AGVs typically have status-color LED strips rather than full body color\n * change; the body legend stays subtle so the LED strip + lamp do the\n * communicating.\n */\nconst BODY_LEGEND = {\n  idle: '#999',\n  moving: '#aaa',\n  charging: '#aaa',\n  error: '#c66',\n  default: '#999'\n}\n\n/**\n * LED strip emissive — the dominant status indicator for AGVs (typically a\n * color-band running around the chassis perimeter).\n */\nconst LAMP_EMISSIVE_LEGEND = {\n  idle: '#222222',\n  moving: '#44ff44',  // green (operating)\n  charging: '#ffaa00', // amber (charging)\n  error: '#ff3333',   // red\n  default: '#222222'\n}\n\nconst NATURE: ComponentNature = {\n  mutable: false,\n  resizable: true,\n  rotatable: true,\n  properties: [\n    {\n      type: 'select',\n      label: 'status',\n      name: 'status',\n      property: {\n        options: [\n          { display: 'Idle', value: 'idle' },\n          { display: 'Moving', value: 'moving' },\n          { display: 'Charging', value: 'charging' },\n          { display: 'Error', value: 'error' }\n        ]\n      }\n    },\n    {\n      type: 'number',\n      label: 'battery',\n      name: 'battery',\n      placeholder: '0..1'\n    },\n    {\n      // AGV travel speed in scene units / second. Used by Mover.moveTo\n      // to derive motion duration. Tune per board scale; forklift convention.\n      type: 'number',\n      label: 'speed',\n      name: 'speed',\n      placeholder: 'units/sec'\n    }\n  ],\n  help: 'scene/component/agv'\n}\n\n// Composition:\n//   FloorBound → Mover → CarrierHolder → ContainerCapacity → Legendable → Placeable → ContainerAbstract\n//\n//   ContainerCapacity: receive() / dispatch() / canReceive() / slots — Mover.pick uses\n//     receive() for slot-tracking and event emission on every cargo transfer.\n//   CarrierHolder:     attachPointFor() — deck-top 3D mount frame; Carriable.added()\n//     calls applyHolderAttachPoint() which uses our override for 3D positioning.\n//   Mover:             moveTo / pick / place / pickAndPlace / executeMission.\n//   FloorBound:        outermost rotation guard.\n//\n// `ContainerAbstract` (not `Container`) — avoids isHTMLElement()=true that would\n// trip the 3D pipeline's addObject DOM-skip gate.\nconst Base = FloorBound(Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract)))))) as unknown as typeof Component & {\n  new (...args: any[]): Component & {\n    isCarrierHolder: boolean\n    isMover: boolean\n    attachPointFor(carrier: Component): CarrierAttachPoint | undefined\n    pick(carrier: Component, options?: MoveOptions): Promise<void>\n    place(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>\n    pickAndPlace(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>\n  }\n}\n\n/**\n * Agv — payload (unit-load) automated guided vehicle. The Kiva-style flat-deck\n * AGV that drives under or carries cargo to/from operation surfaces.\n *\n * **Container-based for cargo containment.** A payload Agv has a flat top\n * deck whose surface is at the scene's operation height. Boxes, parcels,\n * loaded pallets (anything with `placement: 'operation'`) can be added as\n * children — when they are, their natural archetype-derived zPos puts them\n * exactly on the AGV's deck (since AGV depth = operation - floor).\n *\n * For the towing variant (no cargo deck, pulls trailers behind), see Tugger.\n */\n@sceneComponent('agv')\nexport default class Agv extends Base {\n  // `Base` is cast through `typeof Component` so TS sees `state` as an\n  // accessor; `declare state: …` would conflict with TS2610. Override the\n  // getter instead — runtime behavior is identical (just delegates to super).\n  override get state(): AgvState {\n    return super.state as AgvState\n  }\n\n  static legends: Record<string, LegendBinding> = {\n    bodyColor: { from: 'status', legend: BODY_LEGEND },\n    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }\n  }\n\n  /**\n   * AGV sits on its wheels — `floor` archetype. Default depth = operation,\n   * so the top deck lands at the scene's operation height. This is the\n   * design point of payload AGVs: the deck height matches conveyor belt\n   * height, equipment ports, and forklift fork height — cargo transfers\n   * across all of them at the same level.\n   */\n  static placement: PlacementArchetype = 'floor'\n  static align: Alignment = 'bottom'\n  static defaultDepth = (h: Heights) => h.operation - h.floor\n\n  /**\n   * Heading yaw offset (rad). things-scene's vehicle convention is\n   * `vehicle forward = component-local -Z` (= \"rotation=0 → toward canvas\n   * top edge\"); the framework default `Math.PI / 2` aligns with that.\n   * Stated explicitly so the model's forward axis is documented at the\n   * class level rather than relying silently on the framework default.\n   */\n  static yawOffset = Math.PI / 2\n\n  get nature() {\n    return NATURE\n  }\n\n  get anchors() {\n    return []\n  }\n\n  // ── ContainerCapacity ─────────────────────────────────────────────────────\n\n  /**\n   * Single-cargo policy: AGV 는 한 번에 1개의 carrier 만 운반.\n   * 이미 1개를 보유한 상태에서는 `canReceive()` → false → `pick()` 거부.\n   */\n  get slots(): SlotDef[] {\n    return [{ id: 'deck', maxCount: 1 }]\n  }\n\n  /** Accept logistics packages (placement='operation') as deck cargo. */\n  containable(component: Component) {\n    const archetype = (component.constructor as any).placement\n    if (archetype === 'operation') return true\n    return component.isDescendible(this)\n  }\n\n  /**\n   * AGV attach point — flat top deck. Cargo lands on the deck surface\n   * (top of the AGV envelope, which is `+depth/2` in component-local Y).\n   * Multiple cargo items stack vertically by their own depth.\n   *\n   * `attach` is the AGV's `_realObject.object3d` directly — there is no\n   * inner sub-frame the way Forklift has a fork-tip frame, because the\n   * deck moves rigidly with the chassis. Cargo Y reflects the cargoDepth\n   * × slot index stack offset.\n   */\n  attachPointFor(carrier: Component): CarrierAttachPoint | undefined {\n    const ro = this._realObject\n    if (!ro?.object3d) return undefined\n\n    const depth = (this.state.depth as number) ?? 0\n    const slotIdx = this._slotIndexOf(carrier)\n    const cargoDepth = (carrier.state as any).depth ?? 100\n    // 3D origin convention (beta.66+): carrier 의 origin = center.\n    // 데크 표면 (= AGV 상단) y = depth/2. carrier 의 bottom 을 데크 표면에 두려면\n    // carrier center y = deckY + cargoDepth/2. 이후 slot 별로 cargoDepth 씩 stack.\n    const deckY = depth / 2\n\n    return {\n      attach: ro.object3d,\n      localPosition: {\n        x: 0,\n        y: deckY + cargoDepth / 2 + slotIdx * cargoDepth,\n        z: 0\n      },\n      // Phase F: AGV 가 회전하면 cargo 도 같이 회전 (deck 위 고정 lock).\n      carryPolicy: 'follow-holder'\n    }\n  }\n\n  /**\n   * Stack slot = the carrier's index among siblings. Stable because\n   * children order is preserved; no persisted state needed.\n   */\n  private _slotIndexOf(carrier: Component): number {\n    const children = this.components ?? []\n    const idx = children.indexOf(carrier)\n    return idx < 0 ? children.length : idx\n  }\n\n  /**\n   * pick 보완: super.pick 후 carrier 의 자세 정렬 + attachPointFor 강제 재적용.\n   *\n   * 흐름의 마지막에 ContainerCapacity.receive 의 setState({left, top}) 가 표준\n   * pipeline 을 트리거해 obj3d.position 이 attachPointFor 의 localPosition 을 덮어씀.\n   * (= 첫번째 carrier 가 데크 위가 아니라 잘못된 위치/공중에 잡히는 원인)\n   * super.pick 종료 후 attachPointFor 를 다시 적용하고 suppressTransform=true 로\n   * pipeline 의 추가 override 차단. AGV 가 움직이면 carrier 는 scene-graph 통해 자동 추종.\n   */\n  override async pick(carrier: Component, options: any = {}): Promise<void> {\n    // 1-capacity 정책: 이미 1개 보유 시 pick 거부 (moveTo / engage 낭비 방지).\n    if (!(this as any).canReceive(carrier)) {\n      this.trigger('transfer-rejected', {\n        type: 'transfer-rejected',\n        component: carrier,\n        container: this,\n        reason: 'agv-at-capacity'\n      })\n      return\n    }\n    await super.pick(carrier, options)\n    carrier.setState?.({ rotation: 0, rotationX: 0, rotationY: 0 })\n    this._snapToAttachPoint(carrier)\n  }\n\n  private _snapToAttachPoint(carrier: Component): void {\n    const point = this.attachPointFor(carrier)\n    const ro = (carrier as any)._realObject\n    const obj3d = ro?.object3d\n    if (!obj3d || !point?.localPosition) return\n    const lp = point.localPosition\n    obj3d.position.set(lp.x, lp.y, lp.z)\n    if (point.localRotation) {\n      obj3d.rotation.set(point.localRotation.x, point.localRotation.y, point.localRotation.z)\n    } else {\n      obj3d.quaternion.identity()\n    }\n    if (ro) ro.suppressTransform = true\n  }\n\n  /**\n   * 2D — render() sets up the rounded chassis path; the framework fills it\n   * with `fillStyle` (= bodyColor from Legendable) and strokes with\n   * `strokeStyle`. Additional top-down details (bumpers, LiDAR, lift pad,\n   * direction triangle) are drawn in `postrender()`.\n   */\n  render(ctx: CanvasRenderingContext2D) {\n    const { width, height, left, top } = this.state\n    const radius = Math.min(width, height) * 0.12\n    ctx.beginPath()\n    ctx.roundRect(left, top, width, height, radius)\n  }\n\n  /** Top-view accent details — bumpers, lift pad, LiDAR, direction triangle. */\n  postrender(ctx: CanvasRenderingContext2D) {\n    super.postrender?.(ctx)\n\n    const { width, height, left, top } = this.state\n    const cx = left + width / 2\n    const cy = top + height / 2\n    const accentColor = (this.state.lampEmissive as string) || '#44ff44'\n\n    ctx.save()\n\n    // Hi-vis bumper strips (front + rear)\n    const bumperT = Math.min(width, height) * 0.06\n    ctx.fillStyle = '#eeaa00'\n    ctx.fillRect(left + width * 0.15, top, width * 0.7, bumperT)\n    ctx.fillRect(left + width * 0.15, top + height - bumperT, width * 0.7, bumperT)\n    ctx.fillStyle = '#111'\n    ctx.fillRect(left + width * 0.02, top, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.85, top, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.02, top + height - bumperT, width * 0.13, bumperT)\n    ctx.fillRect(left + width * 0.85, top + height - bumperT, width * 0.13, bumperT)\n\n    // Lift pad (center circle — Kiva-style under-shelf lift)\n    const padR = Math.min(width, height) * 0.22\n    ctx.fillStyle = '#4a4a55'\n    ctx.strokeStyle = '#222'\n    ctx.lineWidth = 1\n    ctx.beginPath()\n    ctx.ellipse(cx, cy, padR, padR, 0, 0, Math.PI * 2)\n    ctx.fill()\n    ctx.stroke()\n\n    // LiDAR sensor (small filled circle near front)\n    const lidarR = Math.min(width, height) * 0.07\n    ctx.fillStyle = '#222233'\n    ctx.beginPath()\n    ctx.ellipse(cx, top + height * 0.20, lidarR, lidarR, 0, 0, Math.PI * 2)\n    ctx.fill()\n    ctx.stroke()\n    // Status hint on LiDAR\n    ctx.fillStyle = accentColor\n    ctx.beginPath()\n    ctx.ellipse(cx, top + height * 0.20, lidarR * 0.4, lidarR * 0.4, 0, 0, Math.PI * 2)\n    ctx.fill()\n\n    // Direction-of-travel triangle\n    ctx.fillStyle = accentColor\n    ctx.strokeStyle = '#111'\n    ctx.beginPath()\n    ctx.moveTo(cx, top + height * 0.06)\n    ctx.lineTo(cx - width * 0.06, top + height * 0.13)\n    ctx.lineTo(cx + width * 0.06, top + height * 0.13)\n    ctx.closePath()\n    ctx.fill()\n    ctx.stroke()\n\n    ctx.restore()\n  }\n\n  buildRealObject(): RealObject | undefined {\n    return new Agv3D(this)\n  }\n}\n"]}

package/dist/forklift.d.ts

@@ -1,5 +1,7 @@
 import { Component, ComponentNature, RealObject } from '@hatiolab/things-scene';
+import type { SlotDef, State, Material3D } from '@hatiolab/things-scene';
 import { type Alignment, type CarrierAttachPoint, type Heights, type LegendBinding, type MoveOptions, type PlacementArchetype } from '@operato/scene-base';
+import { Forklift3D } from './forklift-3d.js';
 /**
  * Forklift status — the operating state of a forklift truck.
  *
@@ -13,6 +15,13 @@ import { type Alignment, type CarrierAttachPoint, type Heights, type LegendBindi
  * loaded-vs-empty distinction relevant for fleet visualization.
  */
 export type ForkliftStatus = 'idle' | 'running' | 'lifting' | 'loaded' | 'error';
+/** Forklift 컴포넌트 state */
+export interface ForkliftState extends State {
+    status?: ForkliftStatus;
+    forkHeight?: number;
+    speed?: number;
+    material3d?: Material3D;
+}
 declare const Base: typeof Component & {
     new (...args: any[]): Component & {
         isCarrierHolder: boolean;
@@ -37,6 +46,8 @@ declare const Base: typeof Component & {
  * change the rendering path, only how children's 3D objects are reparented.
  */
 export default class Forklift extends Base {
+    get state(): ForkliftState;
+    _realObject: Forklift3D | undefined;
     static legends: Record<string, LegendBinding>;
     /**
      * Forklift sits on its wheels — `floor` archetype. Default depth is the
@@ -57,14 +68,15 @@ export default class Forklift extends Base {
     get nature(): ComponentNature;
     get anchors(): never[];
     /**
-     * Allow items that flow at operation level (boxes, cartons, parcels, loaded
-     * pallets) to be added as cargo. Restricting by archetype rather than type
-     * means new package components are auto-permitted as they're added to the
-     * scene-base ecosystem.
-     *
-     * Note: this overrides CarrierHolder's default `containable` (which restricts
-     * to `isCarriable === true`). Forklift accepts any operation-archetype
-     * component so cargo authored before adopting Carriable still drops in.
+     * Forks hold up to 3 stacked load units (pallet + boxes).
+     * 3D stacking is handled by `attachPointFor()` (Y offset per slotIdx) —
+     * the slot maxCount here is the hard cap for `canReceive()`.
+     */
+    get slots(): SlotDef[];
+    /**
+     * Forklift 정책: **파레트만** 자식으로 받음. 박스, 카트론, 파셀 등은 받지 않음.
+     * 실제 forklift 가 fork pocket 을 통해 들기 때문에 pocket 구조가 있는 파레트만
+     * 들 수 있음. 박스 등은 AGV 같은 평탄 데크 차량이 운반.
      */
     containable(component: Component): boolean;
     /**
@@ -96,6 +108,29 @@ export default class Forklift extends Base {
      * once the add settles.
      */
     private _slotIndexOf;
+    /**
+     * engage 보완: pick 시 fork blade top 의 world Y 가 carrier (파레트) 의
+     * world center Y 와 일치하도록 forkHeight 를 들어올림. → fork 가 pallet 의
+     * 높이 중간 (= pocket 공간) 에 정확히 위치.
+     *
+     * forklift-3d 의 cargoMountLocal 공식:
+     *   mount.y = -forklift.depth/2 + wheelR + forkHeight + forkH
+     * fork blade top 의 world Y = forklift.world.y + mount.y (origin=center 가정).
+     *
+     * 목표: fork blade top world Y = pallet world center Y
+     *   ⟹ forkHeight = pallet_worldY - forklift_worldY + forklift.depth/2 - wheelR - forkH
+     *
+     * forkHeight clamp: [0, forklift.depth * 0.85] (cargoMountLocal 의 hard cap).
+     */
+    engage(target: Component, kind: 'pick' | 'place', _options?: any): Promise<void>;
+    /**
+     * pick 보완: super.pick 후 자세 정렬 + attachPointFor 강제 재적용.
+     * 흐름의 마지막에 ContainerCapacity.receive 의 setState({left, top}) pipeline 이
+     * obj3d.position 을 덮는 것을 다시 잡음. suppressTransform=true 로 향후 차단.
+     * forklift 가 움직이면 carrier 는 scene-graph 통해 자동 추종.
+     */
+    pick(carrier: Component, options?: any): Promise<void>;
+    private _snapToAttachPoint;
     /**
      * 2D — top-down silhouette of a forklift. Layout (top-down view):
      *

package/dist/forklift.js

@@ -2,7 +2,8 @@ import { __decorate } from "tslib";
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { ContainerAbstract, sceneComponent } from '@hatiolab/things-scene';
+import * as THREE from 'three';
+import { ContainerAbstract, ContainerCapacity, sceneComponent } from '@hatiolab/things-scene';
 import { CarrierHolder, FloorBound, Legendable, Mover, Placeable } from '@operato/scene-base';
 import { Forklift3D } from './forklift-3d.js';
 /** Body color — yellow base hue, modulated slightly by status for at-a-glance state. */
@@ -61,17 +62,17 @@ const NATURE = {
     ],
     help: 'scene/component/forklift'
 };
-// Composition order: Container → Placeable → Legendable → CarrierHolder → Mover.
-// Mover sits OUTSIDE CarrierHolder because Mover's defaults (`pick = this.reparent`,
-// `place = holder.reparent`) rely on CarrierHolder's reparent override being
-// already on the prototype chain. Default impls are instant reparent — Forklift
-// does not yet implement navigation+forkLift motion, so `await forklift.pick(box)`
-// just attaches the box to the forks immediately. Real motion follows in a
-// later commit (path planning, fork actuation animation).
-// FloorBound is the outermost wrap so its rotation guard sees state changes
-// last, after Mover's heading update has run — any ±π corruption (saved-JSON
-// or editor gizmo) is clamped before the next 3D frame applies it.
-const Base = FloorBound(Mover(CarrierHolder(Legendable(Placeable(ContainerAbstract)))));
+// Composition order:
+//   FloorBound → Mover → CarrierHolder → ContainerCapacity → Legendable → Placeable → ContainerAbstract
+//
+//   ContainerCapacity: receive() / dispatch() / canReceive() / slots — Mover.pick uses
+//     receive() (slot-tracking path) instead of the reparent() fallback. Event emission
+//     ('transfer-received', 'transfer-dispatched') fires on every cargo transfer.
+//   CarrierHolder:     attachPointFor() — fork-tip 3D mount frame; Carriable.added()
+//     calls applyHolderAttachPoint() which uses our override for 3D positioning.
+//   Mover:             moveTo / pick / place / pickAndPlace / executeMission.
+//   FloorBound:        rotation guard — outermost, sees state changes last.
+const Base = FloorBound(Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract))))));
 /**
  * Forklift — a powered industrial truck used to lift and transport material
  * over short distances.
@@ -86,6 +87,12 @@ const Base = FloorBound(Mover(CarrierHolder(Legendable(Placeable(ContainerAbstra
  * change the rendering path, only how children's 3D objects are reparented.
  */
 let Forklift = class Forklift extends Base {
+    // `Base` is cast through `typeof Component` so TS sees `state` as an
+    // accessor; `declare state: …` would conflict with TS2610. Override the
+    // getter instead — runtime behavior is identical (just delegates to super).
+    get state() {
+        return super.state;
+    }
     static legends = {
         bodyColor: { from: 'status', legend: BODY_LEGEND },
         lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
@@ -112,22 +119,23 @@ let Forklift = class Forklift extends Base {
     get anchors() {
         return [];
     }
+    // ── ContainerCapacity ─────────────────────────────────────────────────────
     /**
-     * Allow items that flow at operation level (boxes, cartons, parcels, loaded
-     * pallets) to be added as cargo. Restricting by archetype rather than type
-     * means new package components are auto-permitted as they're added to the
-     * scene-base ecosystem.
-     *
-     * Note: this overrides CarrierHolder's default `containable` (which restricts
-     * to `isCarriable === true`). Forklift accepts any operation-archetype
-     * component so cargo authored before adopting Carriable still drops in.
+     * Forks hold up to 3 stacked load units (pallet + boxes).
+     * 3D stacking is handled by `attachPointFor()` (Y offset per slotIdx) —
+     * the slot maxCount here is the hard cap for `canReceive()`.
+     */
+    get slots() {
+        // Single-cargo 정책: 이미 1개 보유 시 `canReceive()` → false → `pick()` 거부.
+        return [{ id: 'forks', maxCount: 1 }];
+    }
+    /**
+     * Forklift 정책: **파레트만** 자식으로 받음. 박스, 카트론, 파셀 등은 받지 않음.
+     * 실제 forklift 가 fork pocket 을 통해 들기 때문에 pocket 구조가 있는 파레트만
+     * 들 수 있음. 박스 등은 AGV 같은 평탄 데크 차량이 운반.
      */
     containable(component) {
-        const archetype = component.constructor.placement;
-        if (archetype === 'operation')
-            return true;
-        // Container's default — accept anything descendible (default things-scene policy).
-        return component.isDescendible(this);
+        return component?.model?.type === 'pallet';
     }
     /**
      * Forklift has a single mount frame: the **forks**. Multiple cargo items
@@ -157,16 +165,31 @@ let Forklift = class Forklift extends Base {
         const attach = ro.modelGroup ?? ro.object3d;
         if (!attach)
             return undefined;
+        // mount: { x, y (fork blade top), z (mid-fork), width, depth (= forkLen) }
         const mount = ro.cargoMount;
         const slotIdx = this._slotIndexOf(carrier);
         const cargoDepth = carrier.state.depth ?? 100;
+        // carrier 의 carrier-local 의 fork 방향 길이 (height = -Z forward 방향).
+        const carrierLenAlongFork = carrier.state.height ?? cargoDepth;
+        // Fork-in-pocket 정렬: forklift 의 fork blade 가 파레트의 fork pocket 공간 안으로
+        // 들어가도록 carrier center y = mount.y (= fork blade top). carrier 의 하반부가 fork
+        // 아래로 내려와 fork 를 감쌈 (pocket 공간). carrier 의 상반부는 fork 위쪽 = 적재 영역.
+        // 이게 실제 forklift-pallet 결합 시각과 일치.
+        // (single-cargo 정책이라 slotIdx 는 항상 0; 멀티 stack 시 cargoDepth 로 stack)
+        const y = mount.y + slotIdx * cargoDepth;
+        // Z (fork 방향): carrier 의 forklift-쪽 면(= +Z, 본체에 가까운 쪽)을 **fork heel
+        // (= 포크의 시작부, 본체와 만나는 지점)** 에 정렬. carrier 본체는 fork tip 쪽으로
+        // 뻗어나가며 forklift 본체 안으로는 절대 파고들지 않음. 큰 파레트는 fork tip 너머로
+        // overhang.
+        // mount.z 는 fork mid, mount.depth 는 fork length. fork heel = mount.z + forkLen/2
+        // (heel 이 본체 쪽 = +Z, less negative).
+        const forkHeelZ = mount.z + mount.depth / 2;
+        const z = forkHeelZ - carrierLenAlongFork / 2;
         return {
             attach,
-            localPosition: {
-                x: mount.x,
-                y: mount.y + slotIdx * cargoDepth,
-                z: mount.z
-            }
+            localPosition: { x: mount.x, y, z },
+            // Phase F: forklift 가 회전하면 fork 의 cargo 도 함께 회전 (fork 위 lock).
+            carryPolicy: 'follow-holder'
         };
     }
     /**
@@ -181,10 +204,83 @@ let Forklift = class Forklift extends Base {
      * once the add settles.
      */
     _slotIndexOf(carrier) {
-        const children = this.children ?? [];
+        const children = this.components ?? [];
         const idx = children.indexOf(carrier);
         return idx < 0 ? children.length : idx;
     }
+    /**
+     * engage 보완: pick 시 fork blade top 의 world Y 가 carrier (파레트) 의
+     * world center Y 와 일치하도록 forkHeight 를 들어올림. → fork 가 pallet 의
+     * 높이 중간 (= pocket 공간) 에 정확히 위치.
+     *
+     * forklift-3d 의 cargoMountLocal 공식:
+     *   mount.y = -forklift.depth/2 + wheelR + forkHeight + forkH
+     * fork blade top 의 world Y = forklift.world.y + mount.y (origin=center 가정).
+     *
+     * 목표: fork blade top world Y = pallet world center Y
+     *   ⟹ forkHeight = pallet_worldY - forklift_worldY + forklift.depth/2 - wheelR - forkH
+     *
+     * forkHeight clamp: [0, forklift.depth * 0.85] (cargoMountLocal 의 hard cap).
+     */
+    async engage(target, kind, _options = {}) {
+        if (kind !== 'pick')
+            return;
+        const myObj3d = this._realObject?.object3d;
+        const targetObj3d = target._realObject?.object3d;
+        if (!myObj3d || !targetObj3d)
+            return;
+        myObj3d.updateWorldMatrix(true, false);
+        targetObj3d.updateWorldMatrix(true, false);
+        const myPos = new THREE.Vector3();
+        const targetPos = new THREE.Vector3();
+        myObj3d.getWorldPosition(myPos);
+        targetObj3d.getWorldPosition(targetPos);
+        const forkliftDepth = this.state.depth ?? 200;
+        const wheelR = forkliftDepth * 0.07;
+        const forkH = forkliftDepth * 0.018;
+        const desired = targetPos.y - myPos.y + forkliftDepth / 2 - wheelR - forkH;
+        const targetForkHeight = Math.max(0, Math.min(desired, forkliftDepth * 0.85));
+        this.setState?.({ forkHeight: targetForkHeight });
+        // mast 재구성 + attach point 재계산 안정화 시간.
+        await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    /**
+     * pick 보완: super.pick 후 자세 정렬 + attachPointFor 강제 재적용.
+     * 흐름의 마지막에 ContainerCapacity.receive 의 setState({left, top}) pipeline 이
+     * obj3d.position 을 덮는 것을 다시 잡음. suppressTransform=true 로 향후 차단.
+     * forklift 가 움직이면 carrier 는 scene-graph 통해 자동 추종.
+     */
+    async pick(carrier, options = {}) {
+        if (!this.canReceive(carrier)) {
+            this.trigger('transfer-rejected', {
+                type: 'transfer-rejected',
+                component: carrier,
+                container: this,
+                reason: 'forklift-at-capacity'
+            });
+            return;
+        }
+        await super.pick(carrier, options);
+        carrier.setState?.({ rotation: 0, rotationX: 0, rotationY: 0 });
+        this._snapToAttachPoint(carrier);
+    }
+    _snapToAttachPoint(carrier) {
+        const point = this.attachPointFor(carrier);
+        const ro = carrier._realObject;
+        const obj3d = ro?.object3d;
+        if (!obj3d || !point?.localPosition)
+            return;
+        const lp = point.localPosition;
+        obj3d.position.set(lp.x, lp.y, lp.z);
+        if (point.localRotation) {
+            obj3d.rotation.set(point.localRotation.x, point.localRotation.y, point.localRotation.z);
+        }
+        else {
+            obj3d.quaternion.identity();
+        }
+        if (ro)
+            ro.suppressTransform = true;
+    }
     /**
      * 2D — top-down silhouette of a forklift. Layout (top-down view):
      *
@@ -308,7 +404,7 @@ let Forklift = class Forklift extends Base {
         super.onchange?.(after, before);
         if (!('forkHeight' in (after ?? {})))
             return;
-        const children = this.children ?? [];
+        const children = this.components ?? [];
         for (const child of children) {
             if (child.applyHolderAttachPoint) {
                 ;