@flextudio/scenario 0.1.0

package/contract-data/runtime/v1/script/scenario-gen-rules.md

@@ -0,0 +1,264 @@
+# 시나리오 생성 단계 — 스크립트 작성 규칙
+
+AI 가 시나리오 메타를 자동 생성할 때 이벤트 스크립트 / Init / After Script 본문에 출력해도 되는 패턴과 그렇지 않은 패턴.
+
+## 1. 핵심 원칙 (한 줄)
+
+> 시나리오 생성 결과물의 스크립트 본문에서 사용 가능한 진입점은 **컬렉션 변형 + 리로드 두 영역뿐**. 그 외의 `f.*` / `_c.*` / `Current.*` / `f.Content().*` 멤버는 출력 금지 — 검증에서 차단.
+
+| 영역 | 허용 멤버 |
+|---|---|
+| 컬렉션 변형 | `f.Collection.addSector(obj, '카테고리')`, `f.Collection.removeSector(status, '카테고리')` (특히 `'all'` 은 카테고리 비우기 표준 idiom) |
+| 컬렉션 직접 접근 | `_c.카테고리[n].키`, `_c.카테고리.activeSector`, `_c.카테고리.set/setValue/remove/add/activate/getSUIDsOfStatus/getSectorsOfStatus`, `sector.set/setValue/delete/setStatus/select/unSelect`, `_c.mapper[suid]` |
+| 리로드 (스텝 전체) | `Current.step.reload(isPositionReset?)`, `Current.step.reloadWithAnimation()` |
+| 리로드 (부분 그룹) | `f.Content(fid).reload()`, `f.Content(fid, sector).reload()`, `f.Content(fid).reloadWithAnimation()` |
+
+그 외에는 모두 **선언적 메타**로 표현. 자세한 매핑은 §3 참조.
+
+## 2. 영역별 규칙
+
+### 2-1. 컬렉션 — `f.Collection.*` vs `_c.*`
+
+> 자세히는 [f_collection.md](./f_collection.md), [../collection/_c.md](../collection/_c.md), [../collection/sector.md](../collection/sector.md).
+
+- **`f.Collection.addSector` + `f.Collection.removeSector` 허용**. 그 외 `f.Collection.{updateSector | moveCategory | removeCategory | createCategory | filter}` 출력 금지.
+- `removeSector(status, '카테고리')` 의 `status` 는 `'all'` (카테고리 비우기 표준 idiom — 카테고리 자체는 유지) / `'added'` / `'updated'` / `'deleted'` / `'selected'` / `'active'`.
+- 값 변경/제거/활성화/카테고리 멤버십은 모두 `_c.카테고리.*` 또는 `sector.*` 메서드를 사용.
+
+### 2-1.1. 스크립트 종류별 섹터 접근 — 위치마다 다른 진입점
+
+스크립트 본문에서 "그 행의 섹터" 를 가져오는 방법은 **스크립트가 어디 박혀있느냐** 에 따라 셋으로 갈린다. 절대 섞이지 않는다 — 정본은 [../collection/_c.md §6.5](../collection/_c.md).
+
+| 스크립트 위치 | 섹터 접근 표준 | 금지 |
+|---|---|---|
+| 이벤트 Script (`Events.<name>` 의 `Action:'Script'` — `Init`/`Loaded`/`Click`/`change` 등) | `_c.카테고리[n].키` / `_c.카테고리.activeSector.키` | `_c.Sector`, bare `sector.X`, `Load.sector.X` |
+| LoadScript (`{% ... %}` 본문 — 컨트롤 표시 단계) | `Load.sector.<field>` | `_c.Sector`, bare `sector.X`, `_c.<카테고리>...` |
+| Filter Custom Script (`ParamBlock.Filters` 의 `FilterType:'Custom'`) | bare `sector.X` (필터링 대상 섹터가 변수로 주입) | `_c.Sector`, `Load.sector.X` |
+
+**핵심 안티패턴** — `_c.Sector` / `_c.sector` 는 _카테고리 이름이 실제로 "Sector" 가 아닌 한_ 존재하지 않는 가짜 핸들. 어느 스크립트 위치에서도 출력 금지. "현재 섹터" 의도라면 위 매트릭스의 위치별 표준으로 교정한다.
+
+```js
+// ✗ 이벤트 스크립트
+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풀일' : '...' %}
+
+{# ✓ Load.sector — 그 행의 섹터는 LoadScript 가 주입 #}
+{% return Load.sector.WorkMon === 'Full' ? '월\n풀일'
+       : (Load.sector.WorkMon === 'Half' ? '월\n반일' : '월\n끔') %}
+```
+
+### 2-2. 리로드 — `Current.step` / `f.Content`
+
+> 자세히는 [current_step.md](./current_step.md), [f_content.md](./f_content.md).
+
+| 멤버 | 출력 허용 |
+|---|---|
+| `Current.step.reload(isPositionReset?)` | ✅ |
+| `Current.step.reloadWithAnimation()` | ✅ |
+| `f.Content(fid).reload()` | ✅ |
+| `f.Content(fid, sector).reload()` | ✅ |
+| `f.Content(fid).reloadWithAnimation()` | ✅ |
+| `Current.step.{moveToNext, moveToPrev, moveToFirst, moveToParent, restart, id, prev, from}` | ❌ |
+| `f.Content(fid).{show, hide, addRow, delRow, selectAll, deselectAll, clickPositionFixed, Scroll}` | ❌ |
+
+### 2-3. 그 외 `f.*` 진입점
+
+| 진입점 | 출력 허용 | 비고 |
+|---|---|---|
+| `f.Collection.addSector` | ✅ | 컬렉션 §2-1 |
+| `f.Date()` | ✅ | 날짜 포맷팅 (하드코딩 대체) |
+| `f.Script.load(...)` | ✅ | 동적 URL 등 부득이한 경우 한정 — **외부 라이브러리는 `Scenario.StyleURLs` 등록을 우선**(정적 URL) |
+| `f.MessageBox(type).setTitle().setDescription().addButton(MOVETYPE_*, label, executeM).show()` | ✅ | 모달 다이얼로그 — 종결자는 `.show()` ([f_messagebox.md](./f_messagebox.md)) |
+| `f.Event(name).runNext()` / `.break()` | ✅ | 다음 이벤트 호출/중단 |
+| `f.Frame.popUp(...)` | ❌ | **다른 시나리오** 호출용. 같은 시나리오 PopUp/SlideUp 은 메타 (`StepDialogType`) 로 표현 |
+| `f.Notification` | ❌ | 전체 사용자 대상 — 사용 금지 |
+| `f.History.*` 조회 | ❌ | 분기 로직은 메타 옵션으로 |
+
+> 공식 문서에 등장하지 않는 멤버 / 본 컨트랙트가 명시하지 않은 멤버는 **모두 금지**. AI 가 임의로 만들어 박지 않도록 strict 검증.
+
+## 3. 작업 ↔ 권장 표현 (총괄)
+
+> **AI 생성 시 intent short-form 우선** — 아래 표의 "intent 표기" 열이 있으면 그 형태로 작성. raw 표기는 intent 가 미지원하는 분기/조건이 있을 때만. intent 카탈로그: [runtime/v1/intent-system/INTENT.md](../intent-system/INTENT.md).
+
+| 하고 싶은 일 | intent 표기 (1순위) | raw 표기 (intent 미지원 / fallback) | 금지 |
+|---|---|---|---|
+| Init 단계 mock 데이터 박기 | `intent.mock: { CtgX: [{...}, ...] }` | `f.Collection.addSector({...}, 'CtgX')` | (대안 없음) |
+| 런타임 단건 섹터 추가 (Init 외) | (intent 미지원) | `f.Collection.addSector(obj, '카테고리')` | (대안 없음) |
+| 활성 섹터 일괄 갱신 | `intent.script: { kind:'updateActive', cat, set:{...}, reload? }` | 가드 2단 + `cur.<k> = <v>;` + reload | `f.Collection.updateSector(...)` (가짜), set 매번 reload |
+| 활성 섹터 완전삭제 | `intent.script: { kind:'deleteActive', cat, reload? }` | 가드 2단 + `cur.release();` + reload | `_c.<Cat>.deleteActiveSector()` (가짜), `.delete()` (deleted 잔존 — `[script-allow]` 차단) |
+| 카테고리 비우기 | `intent.script: { kind:'clearCategory', cat, reload? }` | `f.Collection.removeSector('all', '카테고리')` + reload | `removeCategory + createCategory`, `_c.<Cat>.clear()` (가짜) |
+| 그룹 부분 재렌더 | `intent.script: { kind:'reloadGroup', fid }` | `f.Content(fid).reload()` | 컨트롤 단위 reload (정적 분석 한계) |
+| 모달 다이얼로그 | `intent.script: { kind:'dialog', type, title, body?, buttons:[...] }` | `f.MessageBox(type).setTitle()...show()` | `f.MessageBox().send(...)` (가짜 종결자), `f.Message(...)`, inline function 콜백 |
+| Categories 정의 (Collections type) | `intent.categories: { CtgX: { ckey:'string'\|'int' } }` | (raw 직접 박는 건 권장 X — Panel.* 은 스튜디오 자동 재생성) | size 옵션 / decimal/bool/date 타입 |
+| 특정 상태 섹터 일괄 제거 | (intent 미지원) | `f.Collection.removeSector('deleted', '카테고리')` | (해당 카테고리에 해당 상태가 없을 때만 빈 호출) |
+| 카테고리 비우기/생성 | (생성 시 발생 없음 — 메타로 정적 정의) | `removeCategory + createCategory` |
+| 필터링 표시 | 메타의 `TargetSector.Filters` 로 선언 | `f.Content(fid).hide()` / `f.Collection.filter(...)` |
+| 항목 표시/숨김 | `TargetSector.Filters` 또는 그룹 분기 + 데이터로 구분 | `f.Content(fid).show()`/`hide()` |
+| 행 추가 | `f.Collection.addSector(obj, '카테고리')` + 필요 시 `f.Content(fid).reload()` | `f.Content(fid).addRow(...)` |
+| 행 삭제 | `_c.카테고리.activeSector.release()` (완전삭제) 또는 `_c.카테고리.removeSector(...suids)` + 필요 시 reload | `f.Content(fid).delRow(...)`, `.delete()` (deleted 잔존) |
+| 화면 갱신 (부분) | `f.Content(fid).reload()` (또는 `reloadWithAnimation`) | (대안 없음 — 이게 표준) |
+| 화면 갱신 (스텝 전체) | `Current.step.reload()` (또는 `reloadWithAnimation`) | (대안 없음 — 이게 표준) |
+| **다음 Step 이동** | 메타: `BottomButton.MoveTo:"Next"` + `Next.MoveStepOrder:[...]` 또는 `UseMove:true` + `MoveSteps.MoveStepOrder:[...]` | `Current.step.moveToNext(...)` |
+| **이전 Step 이동** | 메타: `BackButton.Next:"None"` 또는 `BottomButton.MoveTo:"Prev"`/`"Prev_ReStart"` | `Current.step.moveToPrev(...)` |
+| Step 재시작 | 메타: `BottomButton.MoveTo:"Prev_ReStart"` | `Current.step.restart()` |
+| 스텝 ID 분기 | 메타에서 분기 — 별도 Step / Event 로 분리 | `Current.step.id` 조회 분기 |
+| 스크롤 제어 | 메타: `ScrollType` | `f.Content(fid).Scroll.*` |
+
+## 4. 결정 트리
+
+```
+값을 변경하려고 한다
+├─ 클릭/선택된 항목이 대상? → _c.카테고리.activeSector.{key} = 값
+└─ 인덱스 특정 가능? → _c.카테고리[n].{key} = 값
+                     아니면 순회: _c.카테고리.forEach(s => s.{key} = 값)
+
+새 섹터 추가
+└─ f.Collection.addSector(obj, '카테고리')
+   (added 표시 필요 시 sector.setStatus('added'))
+
+섹터 삭제
+└─ sector.release()  (완전삭제 — 생성 시나리오 정본)
+   또는 _c.카테고리.removeSector(...suids)
+   ※ sector.delete() 금지 — added 가 아니면 deleted 잔존 ([script-allow] 차단)
+
+활성 섹터 변경
+└─ _c.카테고리.activate(suid)
+
+화면을 다시 그리고 싶다
+├─ 한 그룹/카드만 → f.Content('fid').reload()  (또는 reloadWithAnimation)
+└─ 스텝 전체     → Current.step.reload()       (또는 reloadWithAnimation)
+
+다음/이전 Step 으로 이동하고 싶다
+└─ 스크립트 출력 금지. 메타의 BottomButton / UseMove 채널로 선언적 표현.
+
+Step 의 ID/이전 Step 정보가 필요하다
+└─ 스크립트 분기 금지. 메타에서 별도 Event / Step 으로 분리.
+```
+
+## 5. 가드와 안전 패턴
+
+### 5-1. 카테고리 존재 가드 (필수)
+
+```js
+if (!_c.카테고리) return;
+const cur = _c.카테고리.activeSector;
+if (!cur) return;
+cur.fStatus = '확정';
+f.Content('f_listGroup').reload();
+```
+
+`_c.카테고리` 가 `undefined` 인 시점이 있다 (`removeCategory` 후, 서브시나리오 클론, restoreCollection 직후). 항상 가드.
+
+### 5-2. activeSector 가드
+
+`Block.activeSector` getter 는 fallback 으로 첫 섹터를 반환하지만 카테고리가 비어있으면 `undefined`.
+
+### 5-3. SUID 사용 시 mapper 검증
+
+```js
+const s = _c.mapper[suid];
+if (!s) return;
+```
+
+## 6. 절대 금지 (validator 가 차단하는 패턴)
+
+- `_c.Sector` / `_c.sector` — 가짜 핸들 (§2-1.1, [../collection/_c.md §6.5](../collection/_c.md)). 이벤트 스크립트는 `_c.<실제카테고리>.activeSector` / `_c.<실제카테고리>[n]`, LoadScript 는 `Load.sector.<field>` 로 교정.
+- 이벤트 Script 본문에서 `Load.sector.X` — LoadScript 전용.
+- LoadScript(`{% %}`) 본문에서 bare `sector.X` 또는 `_c.<카테고리>...` — `Load.sector.X` 로 교정.
+- `f.Collection.{updateSector | moveCategory | removeCategory | createCategory | filter}` 호출 — 모두 차단 (`removeSector` 는 허용)
+- `Current.step.{moveToNext | moveToPrev | moveToFirst | moveToParent | restart}` 호출
+- `Current.step.{id | prev | from}` 조회 (이벤트 스크립트 본문에서)
+- `f.Content(fid).{show | hide | addRow | delRow | selectAll | deselectAll | Scroll}` 호출
+- `f.Content(fid).clickPositionFixed.*`
+- `f.Frame.popUp(...)` (다른 시나리오 호출용 — 같은 시나리오 PopUp/SlideUp 은 메타로 표현)
+- `f.Notification` (전체 발송)
+- `f.History.*` 분기 로직
+- `_c[0].set(...)` 을 `createCategory` 없이 — TypeError 직결
+- `f.MessageBox()` 안에 inline function (`addBtn` / `addButton` 콜백) — `scenario.Events` 의 키 문자열만
+- 컨트롤 단위 `reload()` — 그룹 ID 만 허용
+- 본 컨트랙트가 명시하지 않은 멤버 — strict 차단
+
+### 6-1. 자주 박히는 가짜 핸들 — 명시적 차단 (validator 정규식 박힘)
+
+| 가짜 | 진짜 | 정본 |
+|---|---|---|
+| `_c.<Cat>.clear()` | 카테고리 비우기 표준 idiom 은 `f.Collection.removeSector('all', '<Cat>')` (카테고리 자체는 유지, 섹터만 제거). 활성 섹터만 비우려면 `_c.<Cat>.activeSector.release()` | [f_collection.md §3-1](./f_collection.md), [../collection/sector.md §4-4](../collection/sector.md) |
+| `_c.<Cat>.deleteActiveSector()` | `_c.<Cat>.activeSector.release()` (완전삭제). `.delete()` 는 deleted 잔존(백엔드 동기화용) — 생성 시나리오 금지 (`[script-allow]` 차단) | [../collection/sector.md §4-4](../collection/sector.md) |
+| `_c.<Cat>.activeSector(...)` | `activeSector` 는 프로퍼티. 괄호 없이 `_c.<Cat>.activeSector.<필드>`. 메서드 호출은 `.activeSector.set(...)` / `.release()` / `.setStatus(...)` 로 sector 메서드 체인 | [../collection/category.md §3](../collection/category.md) |
+| `_c.<Cat>.sectors(...)` | `sectors` 는 카테고리 자체(=this, `Category extends Array`). 괄호 없이 `_c.<Cat>.sectors` 또는 동등하게 `_c.<Cat>` / `_c.<Cat>.forEach(...)` | [../collection/category.md §3](../collection/category.md) |
+| `_c.<Cat>.{suids\|active\|name\|status}(...)` | 모두 프로퍼티 — 괄호 없이 | [../collection/category.md §3](../collection/category.md) |
+| `f.MessageBox().send(...)` / `.setBody(...)` / `.chain(...)` / `.addReceiver(...)` | `f.MessageBox(type).setTitle(...).setDescription(...).addButton(MOVETYPE_*, label, executeM).show()` — **종결자는 `.show()`**, 본문 setter 는 `setDescription`. 가짜 `f.Message()` (인스턴스) 도 동일하게 차단 | [f_messagebox.md](./f_messagebox.md) |
+| `{=필드}` (event Script 본문에 박힘) | `{=필드}` 는 Label.labeltext / Button text / ConditionValue 같은 **display 컨텍스트 전용** 토큰. event Script 안에서는 `_c.<카테고리>.activeSector.<필드>` 또는 `_c.<카테고리>[n].<필드>` 로 명시적 참조. JS 문자열 안의 `'{=Name}'` 도 동일 — 그대로 박히면 치환 안 됨 | [../../schema/v1/data-objects.md](../../schema/v1/data-objects.md) `{=Field}` |
+
+## 7. 검증 설계 (validator)
+
+생성된 스크립트 본문(이벤트 스크립트 / Init / After Script / LoadScript) 을 정적으로 분석하여 위 정책을 강제한다.
+
+### 7-1. 화이트리스트 — 허용된 호출 패턴
+
+```
+ALLOW_F_COLLECTION       = /\bf\.Collection\.addSector\s*\(/
+ALLOW_F_DATE             = /\bf\.Date\s*\(/
+ALLOW_F_SCRIPT_LOAD      = /\bf\.Script\.load\s*\(/
+ALLOW_F_MESSAGEBOX       = /\bf\.MessageBox\s*\(/
+ALLOW_F_EVENT            = /\bf\.Event\s*\(/
+ALLOW_CURRENT_RELOAD     = /\bCurrent\.step\.reload(WithAnimation)?\s*\(/
+ALLOW_F_CONTENT_RELOAD   = /\bf\.Content\s*\([^)]*\)\s*\.reload(WithAnimation)?\s*\(/
+ALLOW_C                  = /\b_c\b\.[A-Za-z_]/         // _c.* 은 모두 허용 (직접 대입/메서드)
+ALLOW_SECTOR_METHODS     = /\b\.(set|setValue|setStatus|delete|select|unSelect|activate|add|remove|removeSector|getSUIDsOfStatus|getSectorsOfStatus|forEach|filter)\s*\(/  // 어떤 객체 뒤든 OK (오탐 허용)
+```
+
+### 7-2. 블랙리스트 — 차단해야 하는 호출 패턴
+
+```
+DENY_F_COLLECTION_OTHER  = /\bf\.Collection\.(updateSector|moveCategory|removeCategory|createCategory|filter)\s*\(/   // removeSector 는 허용 ('all' / status 필터)
+DENY_F_FRAME_POPUP       = /\bf\.Frame\.popUp\s*\(/
+DENY_F_NOTIFICATION      = /\bf\.Notification\b/
+DENY_F_HISTORY           = /\bf\.History\.[A-Za-z]/
+DENY_CURRENT_NAV         = /\bCurrent\.step\.(moveToNext|moveToPrev|moveToFirst|moveToParent|restart)\s*\(/
+DENY_CURRENT_INFO        = /\bCurrent\.step\.(id|prev|from)\b/
+DENY_F_CONTENT_OTHER     = /\bf\.Content\s*\([^)]*\)\s*\.(show|hide|addRow|delRow|selectAll|deselectAll|clickPositionFixed|Scroll)\b/
+DENY_C_FAKE_SECTOR       = /\b_c\.[Ss]ector\b/                       // _c.Sector / _c.sector 가짜 핸들 (§2-1.1)
+```
+
+### 7-2.1. 위치 의존 검사 — 스크립트 종류별 섹터 접근
+
+스크립트 본문이 박힌 노드의 종류(이벤트 Script / LoadScript / Filter Custom)에 따라 다음을 분기 검사 — 매트릭스는 §2-1.1.
+
+| 위치 | 추가 차단 패턴 | 사유 |
+|---|---|---|
+| 이벤트 Script 본문 | `\bLoad\.sector\b` | LoadScript 전용 진입점 |
+| LoadScript(`{% %}`) 본문 | `(^|[^.])\bsector\b\s*\.`, `\b_c\.[A-Za-z_]` | 그 행의 섹터는 `Load.sector` 로 주입 — bare `sector` / `_c.<카테고리>` 금지 |
+| Filter Custom `Script` | `\bLoad\.sector\b` | LoadScript 전용 진입점 |
+
+
+### 7-3. unknown 멤버 검출
+
+`f.X` / `_c.Y.Z` / `Current.W` 형태를 정규식으로 추출 → 화이트리스트에 없으면 경고.
+오탐을 줄이기 위해 다음은 화이트리스트:
+- `_c` 뒤의 모든 점/대괄호 접근 (카테고리/섹터 레퍼런스)
+- `sector` / `s` / `cur` / `_c.카테고리[N]` 등 변수에 받은 뒤 점접근 (정적분석 한계)
+
+### 7-4. validator 추가 항목 (`validator.ts` 신규 체크)
+
+- `script_uses_disallowed_navigation` — `Current.step.move*` / `restart` 검출 시 fail
+- `script_uses_disallowed_content_op` — `f.Content().show/hide/addRow/...` 검출 시 fail
+- `script_uses_disallowed_collection_op` — `f.Collection.{updateSector|moveCategory|removeCategory|createCategory|filter}` 검출 시 fail (`removeSector` 는 허용)
+- `script_uses_disallowed_frame_or_history` — `f.Frame.popUp` / `f.History.*` / `f.Notification` 검출 시 fail
+- `script_uses_fake_sector_handle` — `_c.Sector` / `_c.sector` 검출 시 fail (§2-1.1)
+- `script_uses_load_sector_outside_loadscript` — 이벤트/Filter Custom 본문에서 `Load.sector` 검출 시 fail
+- `loadscript_uses_bare_sector_or_c` — LoadScript 본문에서 bare `sector.` 또는 `_c.<카테고리>...` 검출 시 fail
+- 기존 `script_validation` (nested MessageBox 등) 은 유지
+
+각 검출 시 위반 라인과 권장 대체 패턴(§3 매핑) 을 함께 출력.

package/contract-data/schema/v1/SKELETON-SHELL.md

@@ -0,0 +1,120 @@
+# Scenario shell — outer wrap of every scenario JSON
+
+> The outer wrap — ScenarioMeta + `Steps` map + each Step's metadata — is **always raw**. Use the skeleton below; schemas (`scenario.schema.json`, `step.schema.json`, `bottom-buttons.schema.json`) are the validation contract.
+
+## 1. Canonical scenario skeleton (copy → fill `…`)
+
+```jsonc
+{
+  // ─── ScenarioMeta — top-level fixed slots (DO NOT vary const fields) ───
+  "modules":           {},                    // ★ const {}
+  "htmlkey":           "stephtml",            // ★ const "stephtml"
+  "ScenarioTitle":     "",                    // ★ const "" — display name lives in fScenarioName
+  "fConverterVersion": 1,                     // ★ const number 1 (not string)
+  "fScenarioName":     "…",                   // display name (free string)
+  "Collections":       {},                    // ★ const {} — engine fills at runtime
+  "FlexSQLService":    {},                    // ★ const {}
+  "ServiceBinding":    {},                    // ★ const {} — [no-service] strict
+
+  // ─── Steps routing ───
+  "StartSteps":        ["Step1"],             // ≥1 required when Steps non-empty
+
+  // ─── Steps map (keys: ^Step[1-9][0-9]*$) ───
+  "Steps": {
+    "Step1": {
+      "StepName":   "…",                       // internal name
+      "StepType":   "StepView",                // "StepView" | "StepSub". Always author explicitly
+      "StepRow":    0,
+      "StepCol":    0,
+      "Contents":   [                          // pattern invocations + raw Groups
+        // { "<patternName>": { ...props } }
+        // { "ContentsType": "Group", "UseDataConnection": false, "Contents": [ … ] }   // raw Group fallback — UseDataConnection 필수(생략 시 [group-dc])
+      ],
+      "Next":            ["Step2"],            // forward-only StepIds. [] for terminal
+      "UseStepHeader":   false,                // true ⇒ author StepTitle
+      "UseBackButton":   false,                // StepSub forces false
+      "UseBottomButton": false,                // StepSub forces false
+      "UseEvents":       false,                // true ⇒ Events is object (§3); false ⇒ Events is []
+      "Events":          []
+    }
+  },
+
+  // ─── Optional top-level slots ───
+  "Language":     {},                          // i18n map for {{key}} substitution
+  "Events":       {},                          // scenario-level handlers — Script / LinkedEvent only (NO Service/API)
+  "DataSources":  {},                          // for Combo / RadioBox / Search / Tree
+  "Scenario":     { "StyleURLs": [] },         // external JS lib URLs
+  "Panel": {                                   // data model slot — AI emits empty shapes
+    "Collection":    { "Ckeys": [] },
+    "Category":      {},
+    "CategoryOrder": [],
+    "Table":         [],
+    "ExternalTable": [],
+    "AuthKey":       []
+  }
+}
+```
+
+**Common rejections by `flex-scenario validate`:**
+- ❌ Scenario name in `ScenarioTitle` → must be `""`; use `fScenarioName`
+- ❌ `fConverterVersion: "1"` string → must be number `1`
+- ❌ `ServiceBinding: { ... }` non-empty → must be `{}` ([no-service])
+- ❌ Missing `StartSteps` when `Steps` non-empty
+- ❌ `Collections` or `Panel.Collection.Ckeys` non-empty
+- ❌ Authoring `EmbedScenarioPrefix` → schema forbids the key
+
+## 2. Step shape
+
+StepId pattern: `^Step[1-9][0-9]*$`. Always author `StepType: "StepView"` explicitly unless embedding a sub-scenario.
+
+| Field | Type | Notes |
+|---|---|---|
+| `StepName` | `string` | Always author — internal display name |
+| `StepType` | `"StepView"` \| `"StepSub"` | Omit ⇒ runtime treats as StepView |
+| `Contents` | `Group[]` | Page body — patterns + raw Groups |
+| `Next` | `string[]` | Forward-only StepIds. `[]` for terminal |
+| `StepTitle` | `string` | Only with `UseStepHeader: true` |
+| `UseStepHeader` | `boolean` | Top header toggle |
+| `FixedContentsTop` | `Group[]` | Sticky top region (top-bar pattern) |
+| `FixedContentsBottom` | `Group[]` | Sticky bottom — canonical place for primary `button` atom |
+| `UseBackButton` | `boolean` | + author `BackButton` block. **StepSub forces false** |
+| `UseBottomButton` | `boolean` | + author `BottomButtons[]` for fixed-bottom CTAs. **StepSub forces false**. For *inline body* buttons use the `button` pattern instead |
+| `UseEvents` | `boolean` | See §3. **StepSub forces false** |
+
+Step-level styling (`Padding` / `Margin` / `BgStyle`, plus dialog-only `Width` / `Height`) uses **raw** shapes. Engine defaults usually fit — author only when overriding. Read `step.schema.json` for shapes.
+
+## 3. `Step.Events` shape
+
+```jsonc
+// UseEvents: true → Events is an OBJECT
+{
+  "UseEvents": true,
+  "Events": {
+    "StepEventOrder": ["Init", "Loaded"],     // enum the events that fire
+    "Init":           "handlerName_a",        // required for each entry in StepEventOrder (matching key)
+    "Loaded":         "handlerName_b"
+  }
+}
+
+// UseEvents: false → Events MUST be an empty ARRAY (not {})
+{ "UseEvents": false, "Events": [] }
+```
+
+Event enum (6): `Init` / `Loaded` / `OnBackLoaded` / `OnLeave` / `OnForeground` / `ScrollEnd`.
+Each handler name must exist in scenario-level `Events` — else `[event-ref]` fails.
+
+**Common mistakes:**
+- ❌ `UseEvents: false, Events: {}` → must be `[]`
+- ❌ Listing `"Init"` in `StepEventOrder` without the matching `"Init": "handler"` key
+- ❌ Authoring `"Init"` handler key but omitting it from `StepEventOrder` (won't fire)
+
+## 4. When to fetch full schemas
+
+The §1 skeleton covers ~95%. Read the schema file directly for edge cases:
+
+- `scenario.schema.json` — top-level scenarioMeta
+- `step.schema.json` — single Step. Required for **StepSub** (`Protocol` block) and **Dialog variants** (`StepDialogType: "SlideUp"` / `"PopUp"` — unlocks `useDim` / `dimTransp` / `Width` / `Height` / `PopupPosition`)
+- `bottom-buttons.schema.json` — BottomButtons[] item
+- `group.schema.json` — raw Group
+- `data-sources.schema.json` — DataSources map
+- `events.schema.json` — Action shapes for scenario-level Events

package/contract-data/schema/v1/bottom-buttons.md

@@ -0,0 +1,155 @@
+# BottomButtons
+
+Step 의 **하단 고정 버튼 채널**. `Step.BottomButtons` 배열의 각 항목 = 하나의 `BottomButton` 객체.
+
+## 식별
+
+- 위치: `Scenario.Steps[StepId].BottomButtons[*]`
+- 토글: 같은 Step 의 `UseBottomButton: true` (false 면 빈 배열만 허용)
+- 부모: **Step 의 직접 자식**. `Contents` / `FixedContentsTop` / `FixedContentsBottom` 의 자식 아님.
+- StepSub 에서는 `UseBottomButton: false` 자동 강제 → BottomButtons 사용 불가.
+
+## 스키마
+
+`bottom-buttons.schema.json` — 단일 BottomButton 객체 정의. Step 스키마는 `BottomButtons: { type: "array", items: { $ref: "bottom-buttons.schema.json" } }` 로 합성.
+
+## 핵심 필드
+
+| 키 | 타입 | 비고 |
+|---|---|---|
+| `Id` | `f_숫자` | 🔴 필수, 시나리오 전체 유일 |
+| `ButtonName` | string | 화면 표시 텍스트, 다국어 `{{}}` 권장 |
+| `MoveTo` | enum | `Next` \| `None` \| `Prev` \| `Prev_ReStart` \| `Init` |
+| `Next` | object | `MoveTo="Next"` 일 때 **필수**. `{ MoveStepOrder: ["StepN"], StepN: "" }` — **슬롯 값은 빈 문자열** |
+| `Prev` | object | `MoveTo="Prev"` / `"Prev_ReStart"` 일 때 **필수**. `{ MoveStepOrder: [] }` |
+| `Direction` | string | 네비게이션 방향 보조값. Next 버튼 canonical emit 은 `""` |
+| `IsRestored` | bool / `""` | 콜렉션 이전 상태로 복원 (취소/Prev 흐름). Flextudio canonical emit 은 `""` |
+| `IsIgnoreRequired` | bool | `MoveTo="Next"` 시 필수입력 검증 무시 여부. Flextudio Next 버튼 canonical emit |
+| `IsRequired` | bool | `MoveTo="Prev"`/`"Prev_ReStart"` 시 필수입력 보존 여부 |
+| `Events` | object | `{ "Click": "핸들러명" }`. UseEvents 토글 없이 직접 사용 |
+| `LoadScript` | string | 동적 표시/숨김 (`f.bottom().style().display(...)`) |
+| `Width`, `Height` | sizeObject | 버튼 크기 |
+| `Padding`, `Margin` | spacing | 여백 |
+| `BgStyle`, `FontStyle`, `BorderStyle` | style | 시각 스타일 |
+| `ImageStyle` | object | ⚠️ **렌더링 시 적용 제외** (`bottombuttons.js`). 신규 생성 시 누락 권장 |
+| `UseFixedSize` | bool | 고정 크기 사용 |
+| `UseDesign` | bool | 디자인 묶음 적용 |
+
+## MoveTo 분기 규칙 (상호배타)
+
+| MoveTo | 동작 | top-level 키 (반드시) | top-level 키 (금지) |
+|---|---|---|---|
+| `Next` | 다음 Step 으로 이동 | `Next.MoveStepOrder` (1개 이상) + 각 StepN 슬롯 `""` | `Prev` |
+| `Prev` | 이전 Step 으로 이동 | `Prev` (보통 `{ MoveStepOrder: [] }`) | `Next` |
+| `Prev_ReStart` | 이전 Step 이동 + 재시작 | `Prev` | `Next` |
+| `None` | 이동 없음, 이벤트만 실행 | (없음) — `Events.Click` 권장 | — |
+| `Init` | 시나리오 처음 Step 이동 | (없음) | — |
+
+> ⚠️ **Next 버튼에 placeholder Prev 박지 말 것**. 그 반대도 마찬가지. Flextudio 스튜디오는 한 쪽만 emit 한다.
+
+## 핵심 함정 (LLM 생성 실패 사례)
+
+1. **`Next.Step{N}` 슬롯 값이 빈 객체 `{}` 가 아니라 빈 문자열 `""`**:
+   ```jsonc
+   // ❌ 잘못됨 — schema 거부
+   "Next": { "MoveStepOrder": ["Step2"], "Step2": {} }
+
+   // ✅ canonical
+   "Next": { "MoveStepOrder": ["Step2"], "Step2": "" }
+   ```
+   문자열을 받는 이유는 조건/Direction 등 향후 슬롯 확장 여지가 있기 때문 (현재 엔진 emit 은 `""`).
+
+2. **MoveTo=Next 인데 placeholder `Prev: { MoveStepOrder: [] }` 까지 emit** → schema 거부.
+
+3. **MoveTo=Next 인데 `Direction` / `IsIgnoreRequired` 누락** — schema 가 강제하진 않지만 Flextudio canonical 형태에 맞추려면 함께 emit.
+
+## Canonical 키 순서 (Flextudio emit 순서)
+
+JSON 자체는 키 순서를 강제하지 않지만, 가능하면 Flextudio 스튜디오 emit 순서로 작성:
+
+```
+Id → ButtonName → MoveTo → (스타일 키: Width/Height/Padding/Margin/BgStyle/BorderStyle/FontStyle)
+   → IsRestored → IsIgnoreRequired → Direction → Next | Prev
+```
+
+## 예시
+
+### 1) 다음 Step 으로 이동 (canonical)
+
+```jsonc
+{
+  "Id": "f_7",
+  "ButtonName": "{{등록}}",
+  "MoveTo": "Next",
+  "Width": { "SizeValue": 100, "SizeUnit": "%" },
+  "BgStyle": { "UseBackground": true, "BgColor": "var(--colorMain)" },
+  "IsRestored": "",
+  "IsIgnoreRequired": false,
+  "Direction": "",
+  "Next": {
+    "MoveStepOrder": ["Step2"],
+    "Step2": ""
+  }
+}
+```
+
+### 2) 이전 Step (저장 후 복귀)
+
+```jsonc
+{
+  "Id": "f_13",
+  "ButtonName": "{{취소}}",
+  "MoveTo": "Prev",
+  "Width": { "SizeValue": 100, "SizeUnit": "%" },
+  "IsRestored": "",
+  "Prev": { "MoveStepOrder": [] }
+}
+```
+
+### 3) 이벤트만 실행 (이동 없음)
+
+```jsonc
+{
+  "Id": "f_2",
+  "ButtonName": "{{승인}}",
+  "MoveTo": "None",
+  "Events": { "Click": "saveAndApprove" }
+}
+```
+
+## Step 트리에서의 위치
+
+```
+Steps[StepN]
+├── UseBottomButton: true        ← 토글
+├── StepButton: { ... }          ← 영역(컨테이너) 스타일
+├── BottomButtons: [             ← 본 스키마
+│     { Id, ButtonName, MoveTo, ... },
+│     ...
+│   ]
+├── Contents: [...]              ← 별개 (메인 영역)
+├── FixedContentsTop: [...]
+└── FixedContentsBottom: [...]
+```
+
+`StepButton` 은 BottomButtons 영역 자체(컨테이너)의 스타일 묶음이며, 개별 버튼은 BottomButtons 배열의 각 항목이 본인 스타일(`BgStyle` 등)을 따로 가진다.
+
+## 제약
+
+1. **Id 유일성**: 시나리오의 모든 컨트롤/버튼과 충돌 금지 (`^f_[1-9][0-9]*$`).
+2. **StepSub 금지**: StepSub Step 은 자체 화면이 없으므로 BottomButtons 비어있어야 함.
+3. **MoveTo 별 키 상호배타**: `MoveTo="Next"` 이면 top-level `Next` 만, `MoveTo="Prev"/"Prev_ReStart"` 이면 top-level `Prev` 만 (반대편 키 emit 금지 — schema if/then 으로 강제).
+4. **`MoveTo='Next'` + `Next.MoveStepOrder` 1개 이상**: 후보 Step 이 없으면 클릭 시 동작 없음.
+5. **`Next.Step{N}` 슬롯 = 문자열**: canonical 빈 문자열 `""`. 빈 객체 `{}` 는 schema 가 거부.
+6. **자기 자신 Step 참조**: BottomButton 의 `Next` 객체는 임의 Step 참조 가능 (`Step.Next` 의 forward-only 규칙과 별개). 단, 자기 자신 StepId 참조는 후검증에서 차단.
+7. **ImageStyle 효과 없음**: 런타임(`bottombuttons.js`) 이 의도적으로 ImageStyle 적용을 건너뜀.
+
+## 런타임 매핑
+
+- 메타 키 ↔ 런타임 상수 (`public/engine/common/const.js`)
+  - `BottomButtons` ↔ `K_BOTTOMBUTTONS`
+  - `UseBottomButton` ↔ `K_USE_BTMBUTTON`
+  - `ButtonName` ↔ `K_BUTTONNAME`
+  - 컴포넌트 단위 ↔ `COMPONENT_UNIT.BOTTOMBUTTON = 'BottomButton'`
+- 렌더러: `public/engine/runtime/bottombuttons.js` `renderBottomButtons()`
+- fquery 컨트롤 함수: `fControlFuncs['bottom']` (`name()`, `style()` 등) + `fControlFuncs['common']`