@flextudio/scenario 0.1.0

package/contract-data/examples/intent/mock-employee-list.json

@@ -0,0 +1,54 @@
+{
+  "ScenarioTitle": "intent.mock 데모 — 사원 목록",
+  "StartSteps": ["Step1"],
+  "Steps": {
+    "Step1": {
+      "StepType": "StepView",
+      "UseBackButton": true,
+      "Question": "사원 목록",
+      "Events": {
+        "Init": [
+          {
+            "Action": "Script",
+            "intent": {
+              "mock": {
+                "CtgEmployee": [
+                  { "fName": "홍길동", "fAge": 30, "fDept": "개발팀" },
+                  { "fName": "김철수", "fAge": 25, "fDept": "개발팀" },
+                  { "fName": "이영희", "fAge": 28, "fDept": "디자인팀" }
+                ],
+                "CtgDept": [
+                  { "fDeptName": "개발팀", "fHead": "박개발" },
+                  { "fDeptName": "디자인팀", "fHead": "최디자인" }
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "Contents": [
+        {
+          "ContentsType": "Group",
+          "Id": "f_1",
+          "UseDataConnection": true,
+          "DataConnection": {
+            "TargetType": "category",
+            "CategoryName": "CtgEmployee",
+            "DataUsage": "query"
+          },
+          "Contents": [
+            {
+              "ContentsType": "Group",
+              "Id": "f_2",
+              "UseDataConnection": false,
+              "Contents": []
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "Events": {},
+  "ServiceBinding": {},
+  "Collections": {}
+}

package/contract-data/examples/intent/script-cart-flow.json

@@ -0,0 +1,96 @@
+{
+  "ScenarioTitle": "intent.script 5 kind 종합 데모 — 장바구니 흐름",
+  "StartSteps": ["Step1"],
+  "Steps": {
+    "Step1": {
+      "StepType": "StepView",
+      "UseBackButton": true,
+      "Question": "장바구니",
+      "Events": {
+        "Init": [
+          {
+            "Action": "Script",
+            "intent": {
+              "mock": {
+                "CtgCart": [
+                  { "fItem": "아메리카노", "fQty": 1, "fStatus": "대기" },
+                  { "fItem": "라떼", "fQty": 2, "fStatus": "대기" }
+                ]
+              }
+            }
+          }
+        ],
+        "ConfirmEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": {
+                "kind": "updateActive",
+                "cat": "CtgCart",
+                "set": { "fStatus": "확정", "fConfirmedAt": "2024-01-01" },
+                "reload": "f_1"
+              }
+            }
+          }
+        ],
+        "DeleteEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": {
+                "kind": "deleteActive",
+                "cat": "CtgCart",
+                "reload": "f_1"
+              }
+            }
+          }
+        ],
+        "ClearAllEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": {
+                "kind": "dialog",
+                "type": "Alert",
+                "title": "전체 삭제",
+                "body": "장바구니를 모두 비우시겠습니까?",
+                "buttons": [
+                  { "label": "비우기", "event": "DoClearEvent" },
+                  { "label": "취소", "color": "sub" }
+                ]
+              }
+            }
+          }
+        ],
+        "DoClearEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": { "kind": "clearCategory", "cat": "CtgCart", "reload": "f_1" }
+            }
+          }
+        ],
+        "RefreshEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": { "kind": "reloadGroup", "fid": "f_1" }
+            }
+          }
+        ]
+      },
+      "Contents": [
+        {
+          "ContentsType": "Group",
+          "Id": "f_1",
+          "UseDataConnection": true,
+          "DataConnection": { "TargetType": "category", "CategoryName": "CtgCart", "DataUsage": "query" },
+          "Contents": []
+        }
+      ]
+    }
+  },
+  "Events": {},
+  "ServiceBinding": {},
+  "Collections": {}
+}

package/contract-data/examples/intent/script-dialog-confirm.json

@@ -0,0 +1,61 @@
+{
+  "ScenarioTitle": "intent.script.dialog 데모 — 삭제 확인",
+  "StartSteps": ["Step1"],
+  "Steps": {
+    "Step1": {
+      "StepType": "StepView",
+      "UseBackButton": true,
+      "Question": "주문 내역",
+      "Events": {
+        "Init": [
+          {
+            "Action": "Script",
+            "intent": {
+              "mock": {
+                "CtgOrder": [
+                  { "fOrderId": "O-001", "fItemName": "아메리카노", "fAmount": 4500 },
+                  { "fOrderId": "O-002", "fItemName": "라떼", "fAmount": 5000 }
+                ]
+              }
+            }
+          }
+        ],
+        "RequestDeleteEvent": [
+          {
+            "Action": "Script",
+            "intent": {
+              "script": {
+                "kind": "dialog",
+                "type": "Alert",
+                "title": "주문 삭제",
+                "body": "선택한 주문을 삭제하시겠습니까?",
+                "buttons": [
+                  { "label": "삭제", "event": "DeleteConfirmEvent" },
+                  { "label": "취소", "color": "sub" }
+                ]
+              }
+            }
+          }
+        ],
+        "DeleteConfirmEvent": [
+          {
+            "Action": "Script",
+            "Script": "_c.CtgOrder.activeSector.release()\nf.Content('f_listGroup').reload()"
+          }
+        ]
+      },
+      "Contents": [
+        {
+          "ContentsType": "Group",
+          "Id": "f_1",
+          "UseDataConnection": true,
+          "DataConnection": { "TargetType": "category", "CategoryName": "CtgOrder", "DataUsage": "query" },
+          "Contents": []
+        }
+      ]
+    }
+  },
+  "Events": {},
+  "ServiceBinding": {},
+  "Collections": {}
+}

package/contract-data/runtime/v1/collection/README.md

@@ -0,0 +1,119 @@
+# Runtime · Collection 모델 (v1)
+
+`flextudio` 런타임의 데이터 관리 핵심 — **Collection / Category / Sector** 3계층 모델에 대한 정의서.
+스튜디오(에디터)와 런타임이 공유하는 데이터 모델이며, 시나리오 메타의 `Panel.Collection` / `Panel.Category` 정의가 런타임에서 어떤 객체로 전개되어 어떤 생명주기를 갖는지 본 폴더에 정리되어 있다.
+
+> 본 문서들은 다음 두 출처를 1차 근거로 한다.
+> - **공식 가이드** — https://docs.flextudio.com/flextudio/concept (`collection-sector`, `category`, Sector Status 항목)
+> - **런타임 코드** — `public/engine/common/collection.js`, `public/engine/common/status.js`, `public/engine/common/const.js`, `public/engine/interface/publicscript.js`
+
+## 1. 3계층 한눈에 보기
+
+```
+Collection (시나리오당 1개)
+  ├─ mapper       : { suid → Sector }              ← 모든 섹터의 평면 인덱스
+  ├─ status       : CollectionStatus               ← active/added/updated/deleted/selected SUID 목록
+  ├─ _category    : { categoryName → Category }    ← 카테고리 사전
+  └─ Sectors[]    : Block(=Array<Sector>) 자체     ← 시나리오 전체 섹터 평면 배열
+       └─ Sector  : { _SUID, [ckey]: value | Block(InnerBlock) }
+                     - status getter: 'A' | 'U' | 'D' | ''
+                     - isAdded / isUpdated / isDeleted / isSelected / isActive / isLast
+
+Category (Collection._category[name])  ← Array<Sector> 의 부분집합
+  ├─ name
+  ├─ _active : suid                                ← 카테고리 자체의 activeSector
+  └─ activeSector / suids / sectors (this) / status (= collection.status)
+```
+
+용어 매핑 (가이드 ↔ 코드):
+
+| 가이드 용어 | 런타임 객체 | 코드 위치 |
+|---|---|---|
+| 컬렉션(Collection) | `class Collection extends Block` | `collection.js:1076` |
+| 섹터(Sector) | `class Sector extends Object` | `collection.js:26` |
+| 카테고리(Category) | `class Category extends Array` | `collection.js:1121` |
+| 컬렉션키 | `Sector` 객체의 일반 key | (Sector 인스턴스 속성) |
+| InnerBlock | `class Block extends Array` (Sector 값으로 들어가는 중첩 배열) | `collection.js:384` |
+| SUID | `_SUID` (Sector 고유 8+자리 ID) | `const.js:1217` |
+
+## 2. 핵심 불변식
+
+런타임이 가정하는 세 가지 강제 규칙:
+
+1. **단일 컬렉션** — 시나리오당 컬렉션은 1개. 모든 데이터(메인 리스트, 필터, 검색 결과, 입력 폼)는 같은 컬렉션의 섹터로 표현된다.
+2. **단일 mapper** — 컬렉션 안의 모든 섹터(InnerBlock 포함)는 `Collection.mapper[suid]` 하나로 평탄 인덱싱된다.
+3. **카테고리는 부분집합** — Category 는 Collection 안에 이미 존재하는 섹터의 SUID 만을 보관하는 인덱스 배열. 카테고리 자체가 새 데이터를 소유하지 않으며, 카테고리에서 `addSector()` 해도 결국 컬렉션에 추가된 섹터를 카테고리에 등록한다 (`collection.js:1190`).
+
+## 3. 문서 목차
+
+| 파일 | 내용 |
+|---|---|
+| [collection.md](./collection.md) | `Collection` 클래스, 시나리오와 1:1 라이프사이클, 백업/복원, 서브시나리오 클로닝 |
+| [sector.md](./sector.md) | `Sector` 의 생성/병합/삭제, 상태 전이(A/U/D), `set` vs `setValue`, 양방향 reload |
+| [category.md](./category.md) | `Category` 의 역할, `_active` 관리, `addSector` 위임, 카테고리 캡쳐/복원 |
+| [status.md](./status.md) | 5개 상태값(active/selected/added/updated/deleted) 정의·전이·필터 의미 |
+| [lifecycle.md](./lifecycle.md) | 시나리오 시작~종료의 전체 생명주기 (init → bind → reload → capture → restore → release) |
+| [_c.md](./_c.md) | `_c.*` 직접 접근 표준 진입점 + 자주 쓰는 레시피 |
+| [naming.md](./naming.md) | **카테고리명 / 컬렉션키 명명 규칙 + 예약어 / 안티패턴 / 시스템 표준 키** |
+| [../script/](../script/) | `f.*` 스크립트 API (`f.Collection.addSector` 등). **시나리오 생성 시 사용 가능한 `f.Collection.*` 는 `addSector` 단 하나뿐** |
+| [../../../schema/v1/data-objects.md](../../../schema/v1/data-objects.md) | (외부) `DataConnection` / `TargetSector.Filters` 등 메타 표면 카탈로그 — 메타 작성자용 SSOT |
+
+## 4. 빠른 참조 — 상태값 5종
+
+| 상태 | 코드 상수 | Sector getter | 섹터 표시 코드 (`status` getter 반환) | 의미 |
+|---|---|---|---|---|
+| `active` | `C_ACTIVE` (`'active'`) | `isActive` | (별도 표기 없음) | 마지막으로 이벤트를 트리거한 단 1개 섹터. `_collections.activeSector` |
+| `selected` | `C_SELECTED` (`'selected'`) | `isSelected` | (별도 표기 없음) | 사용자가 명시적으로 선택. 다중 가능 |
+| `added` | `C_ADDED` (`'added'`) | `isAdded` | `'A'` | `addSector()` 또는 `DataUsage:"new"` 자동 생성. 저장 시 INSERT 대상 |
+| `updated` | `C_UPDATED` (`'updated'`) | `isUpdated` | `'U'` | `sector.set()` / `setValue()` 호출. 저장 시 UPDATE 대상 |
+| `deleted` | `C_DELETED` (`'deleted'`) | `isDeleted` | `'D'` | `sector.delete()`. 화면에서 사라지나 컬렉션에는 잔류 (저장 시 DELETE) |
+
+> Sector 의 `status` getter (`collection.js:84`) 는 `D > A > U` 우선순위로 단일 문자(`'A'|'U'|'D'|''`)를 반환한다. 동시에 여러 상태가 set 되어 있어도 한 번에 하나만 노출된다.
+
+## 5. 빠른 참조 — 메타→런타임 매핑
+
+| 메타 정의 | 런타임 객체 |
+|---|---|
+| `Panel.Collection.Ckeys: ["fName", ...]` | 사용 가능한 키 화이트리스트 (validator 기준) |
+| `Panel.Category: { CtgItemList: { Ckeys, ... } }` | `Collection._category["CtgItemList"]` 로 생성 |
+| `Panel.CategoryOrder: [...]` | 디버거/직렬화 시 카테고리 순서 |
+| `Group.UseDataConnection: true` + `DataConnection` | `LayoutBinder` 가 해당 Group 의 fId 에 SUID 들을 바인딩 |
+| `DataConnection.DataUsage` | 어떤 SUID 묶음을 바인딩할지 결정 — 메타 표면은 [../../../schema/v1/data-objects.md](../../../schema/v1/data-objects.md), 런타임 동작은 [lifecycle.md §2-3](./lifecycle.md) |
+
+## 6. 실무 표준 작업 패턴
+
+> **시나리오 생성 단계에서 컬렉션 변형은 두 가지 진입점만 사용한다.**
+> - 새 섹터 추가 → `f.Collection.addSector(obj, '카테고리')` (유일하게 허용된 `f.Collection.*` 메서드)
+> - 그 외 모든 변형(값 변경/제거/활성화) → `_c.카테고리.*` 또는 직접 대입
+>
+> 자세한 정책은 [../script/scenario-gen-rules.md](../script/scenario-gen-rules.md) 참조.
+
+```js
+// (1) 값 변경 — 직접 대입이 표준. 화면 반영이 필요하면 그룹 reload
+_c.카테고리[n].콜렉션키 = 값;
+group.reload();           // reload 관련 상세는 별도 문서 예정
+
+// (2) 클릭/선택 기반 — activeSector 사용
+_c.카테고리.activeSector.콜렉션키 = 값;
+
+// (3) 카테고리 존재 가드 — 항상 권장
+if (!_c.카테고리) return;
+const cur = _c.카테고리.activeSector;
+if (!cur) return;
+cur.콜렉션키 = 값;
+
+// (4) 새 섹터 추가 — f.Collection.addSector
+f.Collection.addSector({ fName: '신규' }, '카테고리');
+```
+
+- 직접 대입은 값만 바꾸고 상태/리렌더 트리거는 없음. 한꺼번에 변경 후 마지막에 한 번 reload 하는 흐름에 적합.
+- `sector.set('key', value)` 는 `updated` 상태 자동 부여 + reload 트리거까지 한 번에 수행. 단건 변경에 적합.
+- `_c.카테고리` 가 `undefined` 인 시점이 존재 (`removeCategory` 후, 서브시나리오 클론, 일부 restoreCollection 경로). 접근 전 가드 필수 — 없으면 `Cannot read properties of undefined` 로 즉시 런타임 에러.
+- 생성 단계에서는 `f.Collection.removeSector`/`updateSector`/`moveCategory`/`removeCategory`/`createCategory`/`filter` 출력 금지. 모두 `_c.*` 로 대체.
+
+## 7. 자주 하는 실수 (런타임 에러 직결)
+
+- **`removeSector('all')`** — 카테고리 자체를 파괴. 반드시 `removeCategory + createCategory` 패턴 사용 (`validator.ts:988`).
+- **`createCategory` 없이 `_c.CtgName[0].set()`** — 섹터가 없어 `TypeError`. `DataUsage:"default"` + Init `set()` 패턴은 항상 `removeCategory → createCategory → [0].set()` 순서.
+- **`UseNewSector`/`OnlyIfNoSector`/`UseTargetSector` 를 문자열 `"true"` 로 설정** — boolean `true` 가 아니면 런타임이 분기를 타지 않는다.
+- **컨트롤 단위 `reload`** — 항상 **그룹** Id 에 reload 를 걸어야 한다. 컨트롤 자체는 reload 호출 시 에러.

package/contract-data/runtime/v1/collection/_c.md

@@ -0,0 +1,205 @@
+# `_c` — `_collections` 직접 접근
+
+스크립트 영역에서 컬렉션을 다루는 표준 진입점. **시나리오 생성 단계에서 컬렉션 변형은 거의 모두 `_c.카테고리.*` 를 통해 처리**한다.
+
+> 함수형 래퍼 `f.Collection.*` 는 [../script/f_collection.md](../script/f_collection.md) 참조. **시나리오 생성 단계에서 사용 허용된 `f.Collection.*` 는 `addSector` 와 `removeSector` 두 메서드**. 특히 `f.Collection.removeSector('all', '<Cat>')` 가 카테고리 비우기 표준 idiom. 그 외(`updateSector`, `moveCategory`, `removeCategory`, `createCategory`, `filter`)는 생성 결과물에 출력하지 않는다.
+
+## 1. 두 진입점의 역할 분담
+
+| 진입점 | 정체 | 생성 시 용도 |
+|---|---|---|
+| `_c` (≡ `_collections`) | 컬렉션 인스턴스 자체 | **읽기·변경 전부** — `_c.카테고리[n].콜렉션키 = 값`, `_c.카테고리.activeSector.set(...)`, `_c.카테고리.activate(suid)`, `_c.카테고리.remove(...)` 등 |
+| `f.Collection.addSector` | 새 섹터 추가 함수 | **새 섹터 생성** 1건 |
+
+다른 모든 변형(값 변경/제거/활성화/카테고리 이동)은 `_c.카테고리.*` 메서드 또는 직접 대입으로 처리한다.
+
+## 2. 표준 작업 패턴
+
+```js
+// (1) 값 변경 — 직접 대입이 표준
+_c.카테고리[n].콜렉션키 = 값;
+group.reload();           // reload 관련 상세는 별도 문서 예정
+
+// (2) 클릭/선택 기반 — activeSector 사용
+_c.카테고리.activeSector.콜렉션키 = 값;
+_c.카테고리.activeSector.set('콜렉션키', 값);   // updated 표시 + 자동 reload
+
+// (3) 카테고리 존재 가드 — 항상 권장
+if (!_c.카테고리) return;
+const cur = _c.카테고리.activeSector;
+if (!cur) return;
+cur.콜렉션키 = 값;
+
+// (4) 새 섹터 추가 — 유일하게 f.Collection 사용
+f.Collection.addSector({ fName: '신규' }, '카테고리');
+```
+
+## 3. `_c.*` 자주 쓰는 표현
+
+```js
+// 활성 섹터 조회
+_c.activeSector                       // 컬렉션 단위 active
+_c.카테고리.activeSector              // 카테고리 단위 active
+
+// 카테고리 섹터 순회
+_c.카테고리.sectors.forEach(s => ...)
+_c.카테고리.forEach(s => ...)         // 동일 (Category extends Array)
+
+// SUID 로 직접 조회
+_c.mapper[suid]
+
+// 상태별 조회
+_c.카테고리.getSUIDsOfStatus('added'|'updated'|'deleted'|'selected'|'active'|'all')
+_c.카테고리.getSectorsOfStatus(status)
+_c.added                              // 컬렉션 전체에서 added 인 SUID
+_c.deleted                            // 컬렉션 전체에서 deleted 인 SUID
+
+// 활성 변경
+_c.카테고리.activate(suid)
+_c.카테고리.unActivate()
+
+// 다중 선택
+sector.select() / sector.unSelect()
+
+// 값 변경
+_c.카테고리[n].콜렉션키 = 값            // 상태/리렌더 트리거 없음 — 일괄 변경 후 reload
+_c.카테고리[n].set('key', value)        // updated + reload 자동
+_c.카테고리[n].setValue('key', value)   // updated 표시만, reload 없음
+
+// 섹터 제거
+_c.카테고리.activeSector.release()     // 완전삭제 — 생성 시나리오 정본 (sector.md §4-4)
+_c.카테고리.remove(suid1, suid2)       // 카테고리 인덱스에서만 제거 (컬렉션 본체 유지)
+_c.카테고리.removeSector(...suids)     // 컬렉션에서도 완전 제거
+// ※ .delete() 금지 — added 가 아니면 deleted 상태로 잔존(백엔드 동기화용 표시),
+//    집계/반복 루프 오염. [script-allow] 가 차단.
+```
+
+## 4. `_c.카테고리.add` vs `_c.카테고리.addSector`
+
+| 메서드 | 동작 | 용도 |
+|---|---|---|
+| `_c.카테고리.add(suid)` | 이미 컬렉션에 있는 섹터를 카테고리 인덱스에 추가만 (다중 카테고리 가능) | 검색 필터 결과 인덱스 갱신 |
+| `_c.카테고리.addSector(obj)` | 새 섹터를 컬렉션과 카테고리에 동시 추가 | (생성 단계에서는 `f.Collection.addSector(obj, '카테고리')` 가 동등) |
+
+생성 단계 표준은 `f.Collection.addSector(obj, '카테고리')`. `_c.카테고리.addSector(obj)` 도 동작은 동일하지만 가시성을 위해 `f.Collection.addSector` 형태를 우선 사용한다.
+
+## 5. 자주 쓰는 레시피 (생성 단계 허용 형태)
+
+### 5-1. 신규 등록 폼 → 메인 리스트에 자동 반영 (`DataUsage:"new"`)
+
+메타에서 SlideUp 폼 그룹의 DataConnection 을 `CtgItemList` + `DataUsage:"new"` 로 두면, 입력값이 자동으로 새 섹터에 들어간다. 저장 이벤트는 단순히:
+
+```js
+if (!_c.CtgItemList) return;
+const cur = _c.CtgItemList.activeSector;
+if (!cur) return;
+cur.setStatus('added');                          // added 명시 (필요 시)
+// ... 서버 저장 호출
+group.reload();
+moveToPrev();
+```
+
+### 5-2. 수정 폼 — `DataUsage:"update"` 와 결합
+
+```js
+if (!_c.CtgItemList) return;
+const cur = _c.CtgItemList.activeSector;
+if (!cur) return;
+// 입력 컨트롤이 이미 cur 의 컬렉션키와 양방향 바인딩되어 있어
+// 추가 작업 없이 set 상태로 저장 흐름 진행
+group.reload();
+moveToPrev();
+```
+
+### 5-3. 행 삭제 (Sheet/리스트 공용)
+
+```js
+if (!_c.CtgItemList) return;
+const list = _c.CtgItemList;
+const deletedSuids = list.getSUIDsOfStatus('deleted');
+// 1. 서버 삭제
+await api.deleteMany(deletedSuids.map(suid => list.mapper[suid].fId));
+// 2. 컬렉션에서 정리
+list.removeSector(...deletedSuids);              // 컬렉션 본체에서 제거
+group.reload();
+```
+
+### 5-4. 특정 항목 활성화 + 값 갱신
+
+```js
+if (!_c.CtgItemList) return;
+_c.CtgItemList.activate(targetSuid);
+const cur = _c.CtgItemList.activeSector;
+if (!cur) return;
+cur.fStatus = '확정';
+cur.fApprovedDate = f.Date().format('YYYYMMDD');
+group.reload();
+```
+
+## 6. 직접 대입 vs `set()` vs `setValue()`
+
+| 방식 | updated 표시 | 자동 reload | 용도 |
+|---|---|---|---|
+| `sector.콜렉션키 = 값` | ✗ | ✗ | 다량 변경 후 마지막에 일괄 reload |
+| `sector.set('key', 값)` | ○ | ○ | 단건 변경 + 즉시 화면 반영 |
+| `sector.setValue('key', 값)` | ○ | ✗ | updated 표시는 필요, reload 는 묶어서 |
+
+> reload 동작 자체는 별도 문서로 정리 예정.
+
+## 6.5 스크립트 종류별 섹터 접근 — `_c.Sector` 가짜 핸들 금지
+
+`_c` 는 **카테고리 컬렉션의 루트** 다. `_c.Sector` 라는 표현은 _카테고리 이름이 실제로 "Sector" 가 아닌 한_ 존재하지 않는 가짜 핸들이다. 생성기가 "현재 섹터" 같은 의도로 `_c.Sector` 를 박는 경우가 반복 관찰되므로 정책으로 못박는다.
+
+### 6.5-1. 스크립트 종류 × 섹터 접근 매트릭스
+
+| 스크립트 위치 | 섹터 접근 표준 | 금지 |
+|---|---|---|
+| **이벤트 Script** (`Events.<name>` 의 `Action:'Script'`, `Init` / `Loaded` / `Click` / `change` 등) | `_c.카테고리[n].키` 또는 `_c.카테고리.activeSector.키` (`.set/.setValue` 도 동일 위치) | `_c.Sector`, bare `sector.X`, `Load.sector.X` |
+| **LoadScript** (`{% ... %}` 블록 — 컨트롤/그룹의 표시 단계에서 실행) | `Load.sector.<field>` (`Load.sector.<field> = ...` 쓰기 포함) | `_c.Sector`, bare `sector.X`, `_c.카테고리...` (LoadScript 안에선 그 행의 섹터가 `Load.sector` 로 이미 주어짐) |
+| **Filter Custom Script** (`ParamBlock.Filters` 의 `FilterType:'Custom'` 의 `Script`) | bare `sector.X` (필터링 대상 섹터가 변수로 주입) | `_c.Sector`, `Load.sector.X` |
+
+> "현재 행의 데이터" 를 가져오고 싶을 때 **위치가 어디인지** 부터 판단한다 — LoadScript 안이면 `Load.sector`, 이벤트 Script 안이면 `_c.<카테고리>.activeSector`, Filter Custom 이면 `sector`. 셋은 절대 섞이지 않는다.
+
+### 6.5-2. 안티패턴 ↔ 교정
+
+```js
+// ✗ 이벤트 스크립트 안에서 _c.Sector 라는 가짜 핸들
+var routine = _c.Sector;
+if (routine.WorkMon === 'Full') { ... }
+
+// ✓ 카테고리 이름을 정확히 — activeSector 또는 인덱스
+if (!_c.CtgRoutine) return;
+const routine = _c.CtgRoutine.activeSector;
+if (!routine) return;
+if (routine.WorkMon === 'Full') { ... }
+```
+
+```jinja
+{# ✗ LoadScript 안에서 bare sector / _c #}
+{% return sector.WorkMon === 'Full' ? '월\n풀일' : '...' %}
+{% var r = _c.Sector; return r.WorkMon === 'Full' ? '...' : '...' %}
+
+{# ✓ Load.sector — 그 행의 섹터를 LoadScript 가 이미 주입 #}
+{% return Load.sector.WorkMon === 'Full' ? '월\n풀일'
+       : (Load.sector.WorkMon === 'Half' ? '월\n반일' : '월\n끔') %}
+```
+
+```jsonc
+// Filter Custom — sector 가 변수로 들어옴
+{ "FilterType": "Custom", "Script": "return sector.MealType == _c.CtgOrder[0].MealType" }   // ✓
+{ "FilterType": "Custom", "Script": "return _c.Sector.MealType == ..." }                      // ✗
+```
+
+---
+
+## 7. 금지 / 주의 (생성 단계)
+
+- ❌ `_c.Sector` / `_c.sector` — _카테고리_ 이름이 실제로 "Sector" 가 아닌 한 존재하지 않는 가짜 핸들. 이벤트 스크립트에서는 `_c.<실제카테고리>.activeSector` 또는 `_c.<실제카테고리>[n]` 사용 (§6.5).
+- ❌ 이벤트 스크립트 안에서 `Load.sector.X` — `Load.sector` 는 LoadScript 본문(`{% %}`) 전용.
+- ❌ LoadScript 안에서 bare `sector.X` 또는 `_c.<카테고리>.X` — 그 행의 섹터는 `Load.sector` 로 이미 주입됨 (§6.5).
+- ❌ `f.Collection.{updateSector | moveCategory | removeCategory | createCategory | filter}` — 모두 `_c.*` 로 대체. (`removeSector` 는 허용 — 특히 `removeSector('all','<Cat>')` 가 카테고리 비우기 표준. 자세한 매핑은 [../script/scenario-gen-rules.md](../script/scenario-gen-rules.md))
+- ❌ `_c.카테고리[0].set(...)` 을 카테고리 존재 가드 없이 — TypeError 가능
+- ❌ MessageBox 안에 또 MessageBox / inline function `addBtn` 콜백 — 런타임 실행 안 됨
+- ❌ 컨트롤 자체에 `reload()` — 항상 그룹 ID
+- ⚠️ `f.Collection.addSector(obj)` 후 `added` 상태가 필요하면 명시적으로 `sector.setStatus('added')` 호출
+- ⚠️ `_c.카테고리` 가 `undefined` 일 수 있는 흐름(서브시나리오 클론, restoreCollection 직후, 사용자 스크립트의 removeCategory 직후)에서는 `if (!_c.카테고리) return;` 가드