@flextudio/scenario 0.1.0

package/contract-data/runtime/v1/script/current_step.md

@@ -0,0 +1,112 @@
+# `Current.step`
+
+현재 실행 중인 스텝의 정보 조회와 제어. 정의 위치: `public/engine/interface/publicscript.js:46~154`.
+공식 문서: https://docs.flextudio.com/flextudio/flex/undefined-1/current/current.step
+
+> **시나리오 생성 단계 제약**: `Current.step` 의 멤버 중 **`reload` / `reloadWithAnimation` 두 가지만** 스크립트 출력 허용. 그 외(navigation: moveToNext/Prev/First/Parent, restart, id/prev/from 조회)는 선언적 메타 또는 기존 데이터 흐름으로 처리하므로 생성 결과물에 출력 금지. 자세한 정책은 [scenario-gen-rules.md](./scenario-gen-rules.md).
+
+## 1. 멤버 표
+
+| 멤버 | 타입 | 코드 위치 | 생성 시 허용 |
+|---|---|---|---|
+| `Current.step.id` | getter → `string` | `publicscript.js:49` | ❌ |
+| `Current.step.from` | getter → `string` (= `Current.scenario.id`) | `publicscript.js:54` | ❌ |
+| `Current.step.prev` | object | `publicscript.js:75` | ❌ |
+| `Current.step.prev.id` | getter → `string \| null` | `publicscript.js:78` | ❌ |
+| `Current.step.prev.from` | getter → `string \| null` | `publicscript.js:83` | ❌ |
+| `Current.step.restart()` | function | `publicscript.js:59` | ❌ |
+| `Current.step.reload(isPositionReset?)` | function | `publicscript.js:64` | ✅ |
+| `Current.step.reloadWithAnimation()` | function | `publicscript.js:69` | ✅ |
+| `Current.step.moveToFirst()` | function | `publicscript.js:138` | ❌ |
+| `Current.step.moveToNext(stepId?, ignoreRequired?, transitionEffect?)` | function | `publicscript.js:125` | ❌ |
+| `Current.step.moveToPrev(stepId?, isRestored?, checkRequired?)` | function | `publicscript.js:93` | ❌ |
+| `Current.step.moveToParent(checkRequired?)` | function | `publicscript.js:145` | ❌ |
+
+## 2. 허용된 멤버 — `reload` / `reloadWithAnimation`
+
+### 2-1. `Current.step.reload(isPositionReset?)`
+
+```js
+Current.step.reload();        // 스크롤 위치 보존
+Current.step.reload(true);    // 스크롤 최상단으로 리셋
+```
+
+- 내부 호출: `stepReload(isPositionReset)` ([publicfunctions.js:391](../../../public/engine/interface/publicfunctions.js#L391))
+- 동작:
+  1. `_cStatus.beforeReload(_currentStep)` — 기존 LayoutBinder 임시 저장
+  2. `initRequiredControl()` — 필수입력 추적 리셋
+  3. 현재 스크롤 위치 캡처
+  4. `initTempContents()` + `reloadStep(isAnimate=false)` — 스텝 전체 다시 그림 (Init/Loaded 이벤트는 **재실행 안 함**)
+  5. `_cStatus.afterReload()`
+  6. `setStepScrollEndEvent()` — 스크롤 끝 이벤트 재바인딩
+  7. `isPositionReset` 가 거짓(기본)이면 캡처한 스크롤 위치로 복원
+- 사용 시점: 컬렉션 데이터를 변경한 뒤 화면을 한 번에 다시 그릴 때. 부분 그룹만 다시 그리려면 `f.Content(fid).reload()` 사용.
+
+### 2-2. `Current.step.reloadWithAnimation()`
+
+```js
+Current.step.reloadWithAnimation();
+```
+
+- 내부 호출: `stepReload(false, true)` — `isAnimate=true`
+- 파라미터 없음. 스크롤 위치는 항상 보존(첫 인자 `false`).
+- 애니메이션 효과(페이드/슬라이드 등)와 함께 스텝 재렌더링. Init/Loaded 재실행 없음.
+
+### 2-3. `Current.step.reload` vs `f.Content(fid).reload`
+
+| 비교 항목 | `Current.step.reload()` | `f.Content(fid).reload()` |
+|---|---|---|
+| 범위 | 스텝 전체 | 지정 그룹/레이아웃만 |
+| 비용 | 큼 — 트리 전체 재구성 | 작음 — 부분 재렌더 |
+| 권장 | 다중 그룹 동시 변경, 안전성 우선 | 특정 리스트/카드 한 곳만 변경한 경우 |
+| Init/Loaded | 재실행 ✗ | 재실행 ✗ |
+
+> 둘 중 가능한 좁은 단위(`f.Content(fid).reload()`)를 우선 사용. 그룹 식별이 모호하거나 다수 그룹이 영향받는 흐름에서만 `Current.step.reload()`.
+
+## 3. (참고) 금지 멤버 — 선언적 대체 매핑
+
+| 금지 호출 | 권장 선언적 대체 |
+|---|---|
+| `Current.step.moveToNext('StepN')` | Step.Next 배열 + 다음 중 하나:<br>• `BottomButton[*].MoveTo:"Next"` + `Next.MoveStepOrder:["StepN"]`<br>• Group/Control 의 `UseMove:true` + `MoveSteps.MoveStepOrder:["StepN"]` |
+| `Current.step.moveToNext('StepN', true)` (PopUp/SlideUp) | 대상 Step 의 `StepDialogType:"PopUp"\|"SlideUp"` 설정 + 부모 Step.Next 에 포함 + 위 선언적 채널 사용 |
+| `Current.step.moveToPrev()` | `BackButton.Next:"None"` 또는 `BottomButton.MoveTo:"Prev"`/`"Prev_ReStart"` |
+| `Current.step.moveToFirst()` | (생성 시 거의 없음) |
+| `Current.step.moveToParent()` | 서브시나리오 종료 — 별도 BottomButton 채널 |
+| `Current.step.restart()` | `BottomButton.MoveTo:"Prev_ReStart"` 등 메타 옵션 |
+| `Current.step.id` / `prev.id` 조회 | (필요 시 LoadScript 등 다른 영역에서 — 이벤트 스크립트 본문에서는 분기 로직을 메타 단계 옵션으로 표현) |
+
+## 4. 자주 쓰는 reload 레시피
+
+### 4-1. 카테고리 데이터 일괄 변경 후 스텝 통째 재렌더
+
+```js
+if (!_c.CtgItemList) return;
+_c.CtgItemList.activeSector.fStatus = '확정';
+_c.CtgItemList.activeSector.fApprovedDate = f.Date().format('YYYYMMDD');
+Current.step.reload();
+```
+
+### 4-2. 부분 그룹만 다시 그리기 (성능 우선)
+
+```js
+if (!_c.CtgItemList) return;
+const cur = _c.CtgItemList.activeSector;
+if (!cur) return;
+cur.fStatus = '확정';
+f.Content('f_listGroup').reload();    // 리스트 그룹만 — 자세한 내용은 f_content.md
+```
+
+### 4-3. 검색 필터 적용 후 애니메이션 재렌더
+
+```js
+if (!_c.CtgFilter) return;
+_c.CtgFilter[0].fKeyword = inputValue;
+Current.step.reloadWithAnimation();
+```
+
+## 5. 함정
+
+- **컨트롤 직접 reload 금지** — `f.Content('f_someControl').reload()` 처럼 컨트롤 fId 에 reload 시 에러. 항상 **그룹** Id.
+- **DataConnection 그룹 자체에 reload 금지** — 동일 Id 그룹이 query 로 복제되어 충돌. **래퍼 그룹** Id 로 reload.
+- **Init/Loaded 는 재실행 안 됨** — 초기화 로직이 다시 돌아야 한다면 `Current.step.restart()` 가 필요하지만 시나리오 생성 단계에서는 출력 금지. 메타 옵션(`MoveTo:"Prev_ReStart"`)으로 대체.
+- **PopUp/SlideUp 닫기 후 부모 reload** — PopUp 닫는 BottomButton 의 `Next.MoveStepOrder` 로 부모 Step 으로 돌아가게 해 두면 자동으로 reload 흐름이 처리됨.

package/contract-data/runtime/v1/script/f_collection.md

@@ -0,0 +1,142 @@
+# `f.Collection`
+
+스크립트 영역에서 컬렉션을 변형하는 함수형 래퍼 진입점. 정의 위치: `public/engine/interface/publicscript.js:413~455`.
+
+> **생성 단계 제약**: 시나리오 자동 생성 단계에서 사용 가능한 `f.Collection.*` 는 **`f.Collection.addSector` 하나뿐**. 그 외의 모든 변형은 `_c.카테고리.*` 메서드 또는 직접 대입을 통해 처리한다. 자세한 결정 기준은 [scenario-gen-rules.md](./scenario-gen-rules.md) 참조.
+
+## 1. 메서드 표
+
+| 메서드 | 시그니처 | 내부 호출 | 생성 시 허용 |
+|---|---|---|---|
+| `f.Collection.addSector` | `(obj, category?, targetIdx?)` | `fCreateSector(obj, category, targetIdx)` | ✅ |
+| `f.Collection.removeSector` | `(targetStatus, targetCategory)` | `fRemoveSector(targetCategory, targetStatus)` | ✅ — `'all'` 인자가 카테고리 비우기 표준 idiom (`removeSector('all', '<Cat>')`). 그 외 status 필터 형태(`'deleted'` 등)도 허용 |
+| `f.Collection.updateSector` | `(targetStatus, ckey, value, targetCategory, isReload=true)` | `fUpdateSector` | ❌ — `_c.카테고리[n].콜렉션키 = 값` 또는 `_c.카테고리.activeSector.set(...)` |
+| `f.Collection.moveCategory` | `(targetCategory, targetStatus, newCategory)` | `fMoveToCategory` | ❌ — `_c.대상.add(suid)` + `_c.원본.remove(suid)` |
+| `f.Collection.removeCategory` | `(targetCategory)` | `fRemoveCategory` | ❌ — 생성 단계에서 카테고리 자체를 비우는 일은 없음 |
+| `f.Collection.createCategory` | `(category)` | `fCreateCategory` | ❌ — 메타의 `Panel.Category` 정의로 생성됨 |
+| `f.Collection.filter` | `(ckey, operator, value)` | `fCollectionFilter` | ❌ — 메타 `TargetSector.Filters` 또는 JS Array.filter 사용 |
+
+> 모든 함수는 같은 컬렉션 인스턴스 (`_collections`) 를 변형하므로 `_c.*` 와 효과는 동일하다. 차이는 인터페이스 형태 — `f.Collection.*` 는 함수형 (status/category 인자), `_c.*` 는 객체 메서드 (호출 대상이 명확).
+
+## 2. `f.Collection.addSector` (유일 허용)
+
+```js
+f.Collection.addSector(obj, category, targetIdx)
+```
+
+| 인자 | 타입 | 설명 |
+|---|---|---|
+| `obj` | object \| JSON string | 새 섹터의 초기 데이터. 문자열이면 자동 `JSON.parse`. `_SUID` 포함 시 충돌하면 강제 재발급 |
+| `category` | string? | 카테고리명. 지정 시 컬렉션 추가와 동시에 해당 카테고리에 등록 |
+| `targetIdx` | number? | 카테고리 내 삽입 위치 (정수가 아니면 끝) |
+
+내부 흐름 (`publicscript.js:417` → `collection.js:1537` → `Block.addSector`):
+
+1. `_collections.addSector(obj, category, isForced=true, targetIdx)`
+2. 새 SUID 발급 → `mapper[suid] = sector` → 컬렉션 push → 카테고리 등록
+3. `passChangeCollection()` (디버거 동기화)
+4. 생성된 `Sector` 인스턴스를 반환
+
+```js
+// 단순 추가
+f.Collection.addSector({ fName: '신규', fAge: 0 }, 'CtgItemList');
+
+// 생성된 섹터를 곧장 활성화
+const s = f.Collection.addSector({ fName: '신규' }, 'CtgItemList');
+_c.CtgItemList.activate(s._SUID);
+```
+
+### 2-1. `added` 상태는 자동 부여되지 않는다
+
+`f.Collection.addSector` 자체는 `addStatus(C_ADDED, suid)` 를 호출하지 않는다 (`fCreateSector` 까지만 통과). `added` 표시가 필요하면:
+
+```js
+const s = f.Collection.addSector({ fName: '신규' }, 'CtgItemList');
+s.setStatus('added');                    // 명시적 추가 표시
+```
+
+또는 메타에서 `DataUsage:"new"` 자동 동작을 통해 진입한 섹터는 런타임이 자동으로 added 부여 — 이 경우 스크립트로 `addSector` 를 부를 필요가 없다 (입력값이 자동으로 새 섹터에 들어감).
+
+### 2-2. 카테고리 미존재 가드
+
+```js
+if (!_c.CtgItemList) {
+    f.Collection.createCategory('CtgItemList');   // 사용자 스크립트에서만. 생성 단계 금지
+}
+f.Collection.addSector({ fName: '신규' }, 'CtgItemList');
+```
+
+생성 단계에서는 `Panel.Category` 정의에 의해 카테고리가 항상 존재하도록 메타를 작성하므로 가드가 불필요. 사용자 스크립트에서 `removeCategory` 후 다시 채우는 흐름이라면 가드 필수.
+
+## 3. 허용된 변형 — `removeSector`
+
+### 3-1. `removeSector(targetStatus, targetCategory)`
+
+```js
+// 카테고리 비우기 (표준 idiom — 카테고리 자체는 유지, 섹터만 제거)
+f.Collection.removeSector('all', 'CtgOrderHistory');
+
+// deleted 상태인 섹터만 정리
+f.Collection.removeSector('deleted', 'CtgItemList');
+```
+
+내부적으로 `fRemoveSector(targetCategory, targetStatus)` → `_collections.removeSector(...suids)` 로 위임. `targetStatus`:
+
+| 값 | 의미 |
+|---|---|
+| `'all'` | **카테고리 안의 모든 섹터 제거** (카테고리 인스턴스 자체는 `_category` 사전에 남음 — `removeCategory` 와 다름) |
+| `'added'` / `'updated'` / `'deleted'` / `'selected'` | 해당 상태인 섹터만 제거 |
+| `'active'` | 활성 섹터 제거 (단건) |
+
+> `removeSector('all', ...)` 는 카테고리 **자체를 파괴하지 않는다**. 메타의 `Panel.Category` 정의는 그대로 살아 있고 다음 `addSector('카테고리')` 호출도 정상 동작. 카테고리 자체를 _category 사전에서 빼고 싶을 때만 `removeCategory` 사용 (생성 단계는 거의 없음).
+
+## 3'. (참고) 그 외 메서드 — 사용자 스크립트 전용
+
+생성 단계에서는 사용 금지이지만, 사용자가 운영 중 직접 작성하는 스크립트의 정당한 용례가 있어 시그니처만 정리.
+
+### 3-2. `updateSector(targetStatus, ckey, value, targetCategory, isReload=true)`
+
+```js
+f.Collection.updateSector('selected', 'fStatus', '확정', 'CtgItemList');
+// → CtgItemList 의 selected 섹터들 모두 fStatus = '확정' + 자동 reload
+```
+
+### 3-3. `moveCategory(targetCategory, targetStatus, newCategory)`
+
+원본 카테고리에서 특정 상태인 섹터들을 골라 새 카테고리로 인덱스 이동. 섹터 본체는 컬렉션에 그대로 있고 카테고리 멤버십만 바뀐다.
+
+### 3-4. `removeCategory(category)` / `createCategory(category)`
+
+`removeCategory` 는 카테고리 인스턴스를 `_category` 사전에서 제거 (섹터 본체는 컬렉션에 잔류).
+`createCategory` 는 빈 카테고리 + 빈 섹터 1개를 만든다 (`fCreateCategory` 가 `addSector({}, name)` 호출).
+
+대표 용례 — 마스터 카테고리 패턴:
+
+```js
+// CtgDataListAll = 서버에서 받은 원본
+// CtgDataList    = 화면에 보여줄 필터 결과
+f.Collection.removeCategory('CtgDataList');
+f.Collection.createCategory('CtgDataList');
+_c.CtgDataListAll.sectors
+    .filter(s => s.fName.includes(keyword))
+    .forEach(s => _c.CtgDataList.add(s._SUID));
+group.reload();
+```
+
+### 3-5. `filter(ckey, operator, value)`
+
+ckey 기준 컬렉션 단위 필터. 거의 사용되지 않으며, 메타의 `TargetSector.Filters` 또는 JS 배열의 `filter()` 가 표준.
+
+## 4. `f.*` 의 다른 영역 (요약)
+
+본 폴더에서는 컬렉션 관련만 다룬다. 그 외 `f.*` 의 진입점:
+
+| 진입점 | 용도 |
+|---|---|
+| `f.Event(name).runNext()` / `.break()` | 다음 이벤트 실행 / 중단 |
+| `f.History.step` / `f.History.scenario` | step/scenario 이동 이력 |
+| `f.Frame`, `f.Date()`, `f.Script.load(...)` | 프레임/날짜/외부 스크립트 |
+| `f.MessageBox(type).setTitle().setDescription().addButton/addBtn().show()` | 모달 다이얼로그 (정본: [f_messagebox.md](./f_messagebox.md)) |
+| `f.Notification` | 전체 발송 — 사용 금지 |
+
+생성 단계에서 위 진입점들의 사용 여부는 별도 정책 문서(`scenario-gen-rules.md`) 에서 정의.

package/contract-data/runtime/v1/script/f_content.md

@@ -0,0 +1,133 @@
+# `f.Content`
+
+특정 그룹/레이아웃을 fId 로 가리켜 부분적으로 제어하는 진입점. 정의 위치: `public/engine/interface/publicscript.js:1362` → 내부 `executeContentFunc(fId, suid)` ([fquery.js:2753](../../../public/engine/common/fquery.js#L2753)).
+공식 문서: https://docs.flextudio.com/flextudio/flex/undefined-1/f/f.content
+
+> **시나리오 생성 단계 제약**: `f.Content(fid)` 의 멤버 중 **`reload` / `reloadWithAnimation` 두 가지만** 스크립트 출력 허용. show/hide/addRow/delRow/Scroll 등 그 외는 선언적 메타 또는 컬렉션 변경으로 처리하므로 출력 금지. 자세한 정책은 [scenario-gen-rules.md](./scenario-gen-rules.md).
+
+## 1. 시그니처
+
+```js
+f.Content(fid, sectorOrSUID?)
+```
+
+| 인자 | 타입 | 설명 |
+|---|---|---|
+| `fid` | string (필수) | 대상 그룹/레이아웃의 fId. 컨트롤 fId 사용 시 에러 |
+| `sectorOrSUID` | `Sector \| string` (선택) | 특정 SUID 로 그려진 인스턴스만 대상으로 좁힘. `Sector` 인스턴스를 주면 내부에서 `_SUID` 추출. 미지정 시 해당 fId 의 첫 매칭 또는 전부 |
+
+이벤트 스크립트(Click/Change 등)에서 호출. LoadScript / After Script 등의 컨텍스트에서는 다른 진입점 사용.
+
+## 2. 멤버 표
+
+| 멤버 | 시그니처 | 코드 위치 | 생성 시 허용 |
+|---|---|---|---|
+| `reload` | `()` | `fquery.js:2763` | ✅ |
+| `reloadWithAnimation` | `()` | `fquery.js:2766` | ✅ |
+| `addRow` | `(categoryName, isFocus=true)` | `fquery.js:2769` | ❌ |
+| `delRow` | `(isReleaseSector?)` | `fquery.js:2823` | ❌ |
+| `show` | `()` | `fquery.js:2932` | ❌ |
+| `hide` | `()` | `fquery.js:2940` | ❌ |
+| `selectAll` | `()` | `fquery.js:2949` | ❌ — 다중선택 컨트롤 내부용 |
+| `deselectAll` | `()` | `fquery.js:2974` | ❌ |
+| `clickPositionFixed` | object | `fquery.js:2829` | ❌ — 마우스 위치 기반 floating |
+| `Scroll.offset` | get/set | `fquery.js:3002` | ❌ |
+| `Scroll.toSector(sector, isAnimate?)` | function | `fquery.js:3016` | ❌ |
+| `Scroll.toTop()` | function | `fquery.js:3023` | ❌ |
+| `Scroll.toBottom()` | function | `fquery.js:3029` | ❌ |
+
+## 3. 허용된 멤버 — `reload` / `reloadWithAnimation`
+
+### 3-1. `f.Content(fid).reload()`
+
+```js
+f.Content('f_listGroup').reload();
+```
+
+내부 흐름 ([layout.js:1952](../../../public/engine/runtime/layout.js#L1952) `reloadTargetContent`):
+1. 메타에 `ContentsType` 이 없으면 `ONLY_GROUP_SCRIPT_ERR` — **컨트롤 reload 금지** 가드.
+2. `suid` 미지정 + 그룹이 `UseDataConnection \| UseInnerBlock` → `_fDataContentsReload(fid, isAnimate)` 로 위임 (DC 그룹은 내부에서 SUID 묶음을 다시 평가하여 자식 복제본을 재구성).
+3. 그 외엔 `[data-metaid='${fid}']` 셀렉터로 매칭되는 DOM 요소를 찾아 `Current.sector` 를 해당 SUID 의 섹터로 설정 후 `generateGroup` / `generateLayout` 으로 다시 그림.
+
+> SUID 인자를 줄 때:
+>
+> ```js
+> f.Content('f_card', sector).reload();   // 해당 섹터로 그려진 카드 인스턴스만 부분 재렌더
+> ```
+>
+> 같은 fId 가 query 로 N개 복제된 경우 SUID 로 좁히지 않으면 모든 복제본이 재렌더된다.
+
+### 3-2. `f.Content(fid).reloadWithAnimation()`
+
+```js
+f.Content('f_listGroup').reloadWithAnimation();
+```
+
+내부 호출: `reloadTargetContentWithAnimation(fid, suid, 'none')` → `reloadTargetContent(fid, suid, true)`.
+`reload()` 와 동일하지만 `isAnimate=true` 로 그림 — 페이드/슬라이드 효과.
+
+### 3-3. fId 선택 가이드
+
+| 패턴 | 어떤 fId 에 reload? |
+|---|---|
+| 일반 리스트 (query 그룹) | **그 query 그룹 자체** 의 fId. 다만 그룹이 동일 Id 로 복제된다면 한 단계 위 래퍼 그룹 사용 |
+| Sheet | **래퍼 그룹** Id (Sheet 컨트롤 fId 사용 시 에러) |
+| TimeTable | **래퍼 그룹** Id (TimeTable 컨트롤 fId 사용 시 에러) |
+| Tree | **래퍼 그룹** Id |
+| Scheduler | **래퍼 그룹** Id |
+| 검색 결과 카드 묶음 | 카드들을 감싸는 부모 그룹 (헤더/필터와 같이 묶이지 않은 비반복 래퍼) |
+
+## 4. (참고) 금지 멤버 — 선언적 대체 매핑
+
+| 금지 호출 | 권장 대체 |
+|---|---|
+| `f.Content(fid).show()` | 메타의 `UseEmptyView`, `TargetSector.Filters` (Status/Condition/Custom/Parent), 또는 그룹 자체에 DataConnection 으로 표시할 SUID 묶음을 결정 |
+| `f.Content(fid).hide()` | 동일 — display:none 대신 필터로 미렌더 |
+| `f.Content(fid).addRow(cat)` | `f.Collection.addSector(obj, '카테고리')` + `f.Content(fid).reload()` — 컬렉션 변경 → reload 흐름이 더 명확 |
+| `f.Content(fid).delRow(isReleaseSector)` | `_c.카테고리.activeSector.release()` + `f.Content(fid).reload()` |
+| `f.Content(fid).Scroll.*` | (생성 단계에서 스크롤 제어 필요 없음 — 메타 `ScrollType` 으로 충분) |
+| `f.Content(fid).selectAll()` / `deselectAll()` | 컨트롤이 자체 다중선택 메타로 처리. 스크립트 호출 불필요 |
+| `f.Content(fid).clickPositionFixed.*` | 메타의 절대 배치 / 플로팅 옵션 사용 (FAB 패턴) |
+
+## 5. 자주 쓰는 reload 레시피
+
+### 5-1. 검색 Combo change → 리스트 갱신
+
+메타에서 리스트 그룹의 `TargetSector.Filters` 에 `FilterType:"Custom"` 으로 `_c.CtgFilter[0].fXxx` 를 참조하도록 두고, Combo change 이벤트는 단순히:
+
+```js
+f.Content('f_listGroup').reload();
+```
+
+> 필터 평가는 메타가 책임 — 스크립트는 reload 트리거 한 줄.
+
+### 5-2. 행 추가 (DataUsage:"new" + 신규 폼)
+
+폼 그룹에 `DataUsage:"new"` 가 걸려 있으면 입력값이 자동으로 새 섹터에 들어간다. 저장 BottomButton 이 부모로 돌아가는 흐름이라면 reload 도 명시 불필요 — 부모 진입 시 자동으로 다시 그려짐. 같은 스텝에서 입력 직후 화면 갱신이 필요한 경우만:
+
+```js
+f.Content('f_listGroup').reload();
+```
+
+### 5-3. 다중 그룹 영향 — Step 전체 reload 로 단순화
+
+여러 그룹이 한꺼번에 영향받는 경우는 [current_step.md §2-1](./current_step.md) 의 `Current.step.reload()` 사용.
+
+### 5-4. Embed 섹터 바인딩 갱신 — fid+sector 타겟 리로드
+
+Embed 의 `{%return Load.sector.Field; %}` 는 렌더 시점 1회 평가 — 값이 바뀌어도 자동 갱신 안 됨. 값을 바꾸는 이벤트에서 **Embed 영역의 부모그룹 fid + 그 그룹을 그린 섹터**를 함께 줘서 타겟 리로드:
+
+```js
+// Tree Selected → CtgDeptPick 섹터 갱신 → 배너 Embed 를 감싼 래퍼 그룹 재렌더
+f.Content('f_bannerWrap', _c.CtgDeptPick[0]).reload();
+```
+
+- sector 인자를 빼면 DC 컨텍스트 인스턴스가 좁혀지지 않아 그 행의 `Load.sector` 재평가가 보장되지 않는다 (§3-1 SUID 인자).
+- DC 그룹 자체 fid 금지 — Embed 를 **비연결 래퍼 그룹**으로 감싸고 그 fid 를 사용. 상세: [schema/v1/control/embed.md](../../../schema/v1/control/embed.md) "값 변경 시 갱신".
+
+## 6. 함정
+
+- **컨트롤 fId 사용 금지** — Sheet/TimeTable/Tree/Scheduler 모두 **래퍼 그룹** Id. 컨트롤 자체 fId 에 reload 시 `ONLY_GROUP_SCRIPT_ERR`.
+- **DataConnection 그룹 자체에 reload 했더니 동작이 이상함** — 같은 Id 가 query 로 N 회 복제되었기 때문. 한 단계 상위의 래퍼(비연결) 그룹에 reload.
+- **`f.Content(fid)` 의 `fid` 가 잘못된 경우** — 내부 `_f(fId).getMeta()` 가 fail → `CHECK_ID` 에러. 메타에 실제 존재하는 fId 인지 검증 필요.
+- **show/hide 로 폼 검증 회피** — `display:none` 으로 입력 컨트롤을 숨겨도 필수입력 검사는 동작. 조건부 표시는 `TargetSector.Filters` 또는 별도 그룹 분기로.

package/contract-data/runtime/v1/script/f_messagebox.md

@@ -0,0 +1,132 @@
+# `f.MessageBox`
+
+모달 다이얼로그(메시지 박스) 표시 전용 엔트리. **체이닝 빌더 패턴**으로 사용하며, **종결자는 `.show()`** 다 (`.send()` 가 아님).
+
+> 정의 위치: `public/engine/interface/publicscript.js` (`f.MessageBox` getter → `_fMessageBox`) + `public/engine/interface/publicfunctions.js` (`_fMessageBox` factory).
+
+## 1. 핵심 — 팩토리 시그니처와 체인 메서드
+
+```js
+f.MessageBox(type)         // factory. type 은 박스 스타일 분류.
+  .setTitle(title)         // 제목
+  .setDescription(body)    // 본문
+  .addButton(moveType, label, executeM, isAfter?)
+  .show();                 // 종결자 — 호출하지 않으면 화면에 뜨지 않음
+```
+
+### 1-1. `type` (박스 스타일)
+
+| 상수 | 문자열 | 용도 |
+|---|---|---|
+| `MSG_BOX_ALERT` | `'Alert'` | 경고/주의 |
+| `MSG_BOX_ERROR` | `'Error'` | 에러 |
+| `MSG_BOX_COMPLETED` | `'Completed'` | 완료/성공 |
+
+문자열 리터럴(`'Alert'` 등) 도 그대로 통과한다.
+
+### 1-2. 체인 메서드 (자동완성에 잡히는 공식 7개)
+
+| 메서드 | 시그니처 | 용도 |
+|---|---|---|
+| `setTitle(title)` | `(string)` | 헤더 텍스트 |
+| `setDescription(body)` | `(string)` | 본문 텍스트 |
+| `setDim(useDim)` | `(boolean)` | 뒷배경 디밍 토글 |
+| `addButton(moveType, label, executeM, isAfter?)` | `(string, string, string\|{func,params}\|true, boolean?)` | 풀 시그니처 버튼 — `moveType` 은 `MOVETYPE_*` |
+| `addBtn(label, executeM, color?)` | `(string, string\|{func,params}, boolean?)` | 약식 버튼 — `color=true` 면 보조 스타일 |
+| `show()` | `()` | **체인 종결자.** 호출해야 박스가 뜬다 |
+| `hide()` | `()` | 외부에서 강제 닫기 (보통 내부에서 자동 호출) |
+
+> 모든 setter/adder 는 `this` 를 반환 (체이닝 가능). `show()` 도 `this` 를 반환하지만 종결자로만 사용한다.
+
+### 1-3. `executeM` (버튼 액션)
+
+`addButton` / `addBtn` 의 3번째 인자 `executeM` 에 들어갈 수 있는 값:
+
+| 값 | 의미 |
+|---|---|
+| `null` / `undefined` | 닫기만 (별도 이벤트 없음) |
+| `'EventName'` (string) | `scenario.Events['EventName']` 핸들러 실행 |
+| `{ func, params }` | 런타임 헬퍼 호출 — 보통 엔진 내부에서만 사용 |
+| `true` | (`addButton` 전용) `isAfter=true` 옵션과 함께 흐름 재개 |
+
+⚠ **inline function 콜백 금지** — `addButton(type, label, () => {...})` 형태는 직렬화 단계에서 보존되지 않는다. 항상 `scenario.Events` 의 키 문자열만.
+
+### 1-4. `moveType` (`addButton` 전용)
+
+`addButton` 첫 인자에 들어가는 `MOVETYPE_*` 상수 — 버튼 클릭 후 어느 Step 으로 이동할지 결정.
+
+| 상수 | 문자열 | 동작 |
+|---|---|---|
+| `MOVETYPE_NONE` | `'None'` | 현재 Step 유지 |
+| `MOVETYPE_NEXT` | `'Next'` | 다음 Step |
+| `MOVETYPE_PREV` | `'Prev'` | 이전 Step |
+| `MOVETYPE_INIT` | `'Init'` | 첫 Step 으로 |
+| `MOVETYPE_CLOSE` | `'Close'` | 시나리오 종료 |
+| `MOVETYPE_JUMPTO` | `'JumpTo'` | 지정 Step 으로 점프 |
+
+`addBtn` 은 `moveType` 인자가 없고 이벤트로만 분기한다 — 단순 다이얼로그면 `addBtn` 으로 충분.
+
+## 2. 사용 패턴
+
+### 2-1. 가장 단순한 알림
+
+```js
+f.MessageBox('Completed')
+  .setTitle('완료')
+  .setDescription('승인처리 되었습니다.')
+  .addButton(MOVETYPE_PREV, '닫기', true)
+  .show();
+```
+
+### 2-2. 두 버튼 — 확인/취소
+
+```js
+f.MessageBox('Alert')
+  .setTitle('삭제하시겠습니까?')
+  .setDescription('이 작업은 되돌릴 수 없습니다.')
+  .addBtn('확인', 'DeleteConfirmEvent')
+  .addBtn('취소', null, true)
+  .show();
+```
+
+- `addBtn` 의 두 번째 인자는 **이벤트명 문자열** 또는 `null`.
+- 세 번째 `color=true` 면 보조(취소) 스타일.
+
+### 2-3. 에러 박스 + 분기 이벤트
+
+```js
+f.MessageBox('Error')
+  .setTitle('오류')
+  .setDescription('네트워크에 연결할 수 없습니다.')
+  .addButton(MOVETYPE_NONE, '재시도', 'RetryEvent')
+  .addButton(MOVETYPE_INIT, '처음으로', null)
+  .show();
+```
+
+## 3. 자주 틀리는 패턴
+
+| 가짜 호출 | 의도했던 것 | 교정 |
+|---|---|---|
+| `f.MessageBox().send()` | 박스 출력 | **`.show()`** 가 종결자. `send()` 는 미존재 |
+| `f.MessageBox().setBody(...)` | 본문 설정 | `setDescription(...)` |
+| `f.MessageBox().addReceiver(...)` | 수신자 지정 | 다이얼로그는 현재 사용자에게만 표시 — 수신자 개념 없음 |
+| `f.MessageBox().chain(...)` | 토스트/안내 | 미존재. 토스트는 `f.Toast` 채널 |
+| `f.MessageBox.show(...)` | 정적 호출 | `f.MessageBox()` 로 인스턴스 생성 필수 (factory) |
+| `addBtn('확인', () => {...})` | inline 콜백 | `scenario.Events` 의 키 문자열만 |
+| MessageBox 안에 또 MessageBox | 연쇄 다이얼로그 | 첫 박스의 버튼 이벤트 핸들러에서 두 번째 박스를 호출 |
+
+## 4. 사용 위치 제약
+
+- **Init 핸들러에서 호출 금지** — Init 은 mock 데이터 박는 단계. 다이얼로그는 사용자 트리거(`Click` / `Change` / `Loaded` 후) 에서만 허용. 검증기 `[script-allow]` 의 `SCRIPT_INIT_DENY_PATTERNS` 가 차단.
+- **LoadScript(`{% %}`) 안에서 호출 금지** — LoadScript 는 표시 단계의 값 계산 전용. 박스 출력은 이벤트 Script 에서.
+- **Filter Custom Script 안에서 호출 금지** — 필터 본문은 boolean 반환 전용.
+
+## 5. 검증 (validator)
+
+`core/validators.mjs` 의 `SCRIPT_DENY_PATTERNS` / `SCRIPT_INIT_DENY_PATTERNS` 가 다음을 정적 차단:
+
+- `f.MessageBox().chain(...)` / `.send(...)` / `.setBody(...)` / `.addReceiver(...)` — 가짜 메서드
+- (Init) `f.MessageBox(` 호출 자체
+- `f.Notification` — 사용 금지 (전체 발송 위험)
+
+추가 가짜 메서드가 운영 결과에서 반복 검출되면 이 문서 §3 표를 갱신하고 deny 정규식을 추가한다.