@flextudio/scenario 0.1.0

package/contract-data/schema/v1/control/embed.md

@@ -0,0 +1,211 @@
+# Embed
+
+> 공식 가이드: <https://docs.flextudio.com/flextudio/scenario/component/control/embed>
+
+raw HTML 을 화면에 직접 삽입하는 컨트롤. `Embed` 속성에 HTML 문자열을 두면 그대로 렌더된다 — 내장 컨트롤로 표현이 어려운 비디오/iframe/외부 라이브러리 캔버스/style 주입 등에 사용.
+
+## 스키마
+
+`control/embed.schema.json` — `controlBase` + `Embed` (raw HTML).
+
+## 필수 / 핵심 규칙
+
+| 속성 | 비고 |
+|---|---|
+| `Embed` | ★ raw HTML 문자열. `<video>` / `<iframe>` / `<canvas>` / `<div>` / `<style>` 등. 섹터 값 바인딩은 `{%return Load.sector.Field; %}` (LoadScript 토큰) — **`{=Field}` 는 Embed 안에서 치환되지 않음, 사용 금지 (`[embed-bind]`)**. |
+| `Caption` | ★ **반드시 빈 문자열 `""`** — Embed 본체에 그대로 표시되므로 ControlDefaultName 등 내부명 두면 노출됨 (스키마 const "" 강제). |
+| `Width` / `Height` | 콘텐츠에 맞게. style-only Embed 는 0px × 0px (보이지 않게). |
+
+## 기본 예시 — 비디오 임베드
+
+```jsonc
+{
+  "ControlType": "Embed",
+  "Id": "f_46",
+  "ControlDefaultName": "Embed1",
+  "ControlName2": "Embed1",
+  "Caption": "",
+  "Width":  { "SizeValue": 100,  "SizeUnit": "%" },
+  "Height": { "SizeValue": "200", "SizeUnit": "px", "MatchText": false },
+  "isColumnCtrl": false,
+  "Embed": "<video src=\"https://example.com/{%return Load.sector.flexFileKey; %}\" style=\"width:100%;height:100%\" controls></video>"
+}
+```
+
+## 섹터 값 바인딩 — `{%return Load.sector.Field; %}`
+
+Embed raw HTML 안에서 섹터 값을 표시하려면 **LoadScript 토큰** `{% ... %}` 을 쓴다 — DC 그룹 안의 Embed 면 그 행의 섹터가 `Load.sector` 로 주입된다 (LoadScript 컨텍스트와 동일, [events.md](../events.md) §2.1 / [runtime/v1/collection/_c.md §6.5](../../../runtime/v1/collection/_c.md)).
+
+```jsonc
+// DC 그룹 (CategoryName: "CtgDeptPick") 안의 Embed
+"Embed": "<div>선택 부서: <b>{%return Load.sector.DeptPickName; %}</b></div>"
+```
+
+> ⛔ **`{=Field}` 금지 (`[embed-bind]`)** — `{=Field}` 는 Label.labeltext / Button text 류 **display 전용 토큰**으로 Embed raw HTML 에서는 치환되지 않고 문자 그대로 노출된다. `checkEmbedSectorBinding()` 이 차단.
+
+### ★ 토큰만으로는 연결이 보장되지 않는다 — 보장 조건 3가지
+
+`Load.sector` 는 엔진의 전역 렌더 커서(`Current.sector`)를 읽는 getter 일 뿐이다 (engine publicscript.js). Embed 렌더는 다른 컨트롤과 달리 **sector 인자 없이** `replaceExpressions(embedHTML)` 를 타므로 (engine control.js `createEmbedVideo` — `{=Field}` 가 안 되는 이유이기도 함), `{%Load.sector.ckey%}` 가 실제 그 행의 값으로 평가되려면 다음이 모두 성립해야 한다:
+
+| # | 조건 | 깨졌을 때 증상 | 보장 수단 |
+|---|---|---|---|
+| 1 | **조상 DC 그룹** — `UseDataConnection:true + CategoryName` 그룹 아래에 Embed 가 있어야 함. 조상 DC 가 섹터별 렌더 중일 때만 `Current.sector` 가 그 행을 가리킴 (engine layout.js) | DC 밖이면 `Load.sector` = undefined → `{% %}` try/catch 가 삼켜 **조용히 빈 문자열** | `[embed-bind]` 가 정적 차단 |
+| 2 | **ckey 가 그 카테고리 섹터에 실제 존재** — Init mock(`intent.mock`/addSector) 또는 컨트롤 쓰기(Ckeys/CollectionMapper)로 채워져야 함 | 키 없으면 undefined → 빈 문자열 (에러 없음) | [mockup-data.md](../mockup-data.md) ★ 짝 규칙 (정적 검증 없음 — 직접 확인) |
+| 3 | **값 변경 시 재평가** — `{% %}` 는 렌더 시점 1회 평가 | 값 바뀌어도 화면 그대로 | 아래 "값 변경 시 갱신" — fid+sector 타겟 리로드 |
+
+### 🔴 값 변경 시 갱신 — fid+sector 타겟 리로드 필수
+
+`{% %}` 토큰은 **렌더 시점에 1회 평가**된다 — 바인딩한 키의 컬렉션 값이 바뀌어도 Embed 는 자동 갱신되지 않는다. 값을 바꾸는 이벤트(Tree Selected / Combo change / 입력 change 등)에서 **해당 영역의 부모그룹을, 그 그룹을 그리는 섹터까지 한 번에** 타겟 리로드해야 한다:
+
+```js
+f.Content('<Embed 영역 부모그룹 fid>', <그 그룹을 그린 섹터>).reload();
+```
+
+- `fid` 만 주고 `sector` 를 빼면 안 된다 — DC 컨텍스트 안의 인스턴스를 섹터(SUID)로 좁혀야 그 행의 `Load.sector` 로 재평가된다 ([runtime/v1/script/f_content.md §3-1](../../../runtime/v1/script/f_content.md)).
+- **DC 그룹 자체 fid 는 reload 금지** (복제 문제 — group.md 함정). Embed 를 **비연결 래퍼 그룹**으로 감싸고 그 래퍼 fid 를 리로드한다.
+
+```jsonc
+// 패턴: Tree 선택 → 배너 Embed 갱신
+// [DC 그룹 f_3010 (CtgDeptPick)] > [TreeCard] + [BannerWrap f_3014 (UseDataConnection:false)] > [Embed]
+// Tree.Events.Selected: "DeptTreeSelect_E"
+"DeptTreeSelect_E": [
+  { "Action": "Script", "Script": "f.Content('f_3014', _c.CtgDeptPick[0]).reload()" }
+]
+```
+
+## ★ 외부 라이브러리 연동 패턴 (Chart / 지도 / QR 등)
+
+> **핵심:** `<script>` 태그는 `Embed` 안에 **직접 넣을 수 없다.** 외부 라이브러리 URL 은 **`Scenario.StyleURLs` 배열에 등록하는 것이 표준** — 시나리오 진입 시 자동 로드되므로 별도 로딩 호출이 필요 없다.
+
+### 표준 흐름
+
+1. **유니크한 id 부여한 `<div>` / `<canvas>`** 를 Embed 안에 둔다.
+2. 외부 라이브러리 URL 은 **`Scenario.StyleURLs`** 배열에 추가한다 (권장 — 진입 시 자동 로드).
+   - `f.Script.load(url, callbackEventName)` 도 화이트리스트상 허용되지만, **정적으로 알 수 있는 라이브러리는 `StyleURLs` 에 두는 것을 우선**한다. `f.Script.load` 는 런타임에 동적으로만 결정되는 URL 등 부득이한 경우로 한정.
+3. Step **`Loaded`** (DOM 준비 완료) 이벤트에서 `document.getElementById(uniqueId)` 로 DOM 을 잡아 **실제로 렌더**한다. (`StyleURLs` 로 미리 로드돼 있으므로 라이브러리 전역 객체를 바로 사용.)
+
+> 🔴 **CRITICAL — 로드 ≠ 렌더 (`[embed-render]`)**: 라이브러리를 `StyleURLs`(또는 `f.Script.load`)로 불러오는 것만으로는 **아무것도 안 그려진다.** `<canvas>` / 빈 `<div id=…>` 를 둔 Embed 는 **반드시** host Step 의 `Loaded` 핸들러에서 `document.getElementById(...)` 로 DOM 을 잡아 `new Chart(...)` / `new naver.maps.Map(...)` 등 **렌더 코드를 직접 실행**해야 한다. 로딩 호출만 넣고 그리기를 빼먹으면 빈 영역만 남는다 — `checkEmbedRender()` 가 이 누락을 차단(`strict_embed_render:false` 로 비활성).
+
+> ⚠️ **`Loaded` vs `Init`** — Chart/Canvas 처럼 DOM 이 그려진 뒤 즉시 작업하면 `Loaded`. 지도처럼 라이브러리 콜백으로 진입하는 패턴은 `Init` 에서 처리.
+>
+> ⛔ **Tab 컨트롤 내부 LinkedStep 에는 Embed 자체를 두지 말 것** (`[tab-embed]`) — 탭 내부 Step 은 `Loaded`/`Init` 이 미실행이라 위 초기화 흐름이 돌지 않는다. [control/tab.md](tab.md) 참조.
+>
+> `Loaded` 이벤트가 있는 Step 으로 **뒤로 돌아가는 BottomButton 은 `Prev_ReStart`** 사용 (재진입 시 차트/지도/캔버스 재초기화).
+
+### 예시 A — Chart.js (Step Loaded)
+
+```jsonc
+// Embed control
+{
+  "ControlType": "Embed",
+  "Id": "f_chart",
+  "ControlDefaultName": "ChartEmbed", "ControlName2": "ChartEmbed",
+  "Caption": "",
+  "Width":  { "SizeValue": 100,  "SizeUnit": "%" },
+  "Height": { "SizeValue": "300", "SizeUnit": "px", "MatchText": false },
+  "isColumnCtrl": false,
+  "Embed": "<canvas id=\"myChart\"></canvas>"
+}
+```
+
+**권장 — 라이브러리는 `Scenario.StyleURLs` 에 등록** (진입 시 자동 로드, 별도 로딩 호출 불요):
+
+```jsonc
+{
+  "Scenario": {
+    "StyleURLs": [
+      "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.8.0/Chart.bundle.min.js"
+    ]
+  }
+}
+```
+
+```javascript
+// Step Loaded 이벤트 — StyleURLs 로 이미 로드돼 있으므로 Chart 전역을 바로 사용.
+var ctx = document.getElementById('myChart').getContext('2d');
+new Chart(ctx, {
+  type: 'bar',
+  data: { labels: ['1월','2월','3월'], datasets: [{ label: '매출', data: [120, 190, 300] }] },
+  options: { responsive: true }
+});
+```
+
+> `f.Script.load('https://.../Chart.bundle.min.js', null, null)` 도 허용되지만, 위처럼 정적 URL 은 `StyleURLs` 등록을 우선한다.
+
+### 예시 B — 네이버지도 (StyleURLs + Step Loaded 렌더)
+
+```jsonc
+// 라이브러리: Scenario.StyleURLs 에 등록 (진입 시 자동 로드)
+{ "Scenario": { "StyleURLs": ["https://openapi.map.naver.com/openapi/v3/maps.js?ncpClientId=YOUR_KEY"] } }
+
+// Embed control
+{
+  "ControlType": "Embed",
+  "Id": "f_map",
+  "Caption": "",
+  "Width":  { "SizeValue": 100,  "SizeUnit": "%" },
+  "Height": { "SizeValue": "300", "SizeUnit": "px", "MatchText": false },
+  "Embed": "<div id=\"naverMap\" style=\"width:100%;height:100%;\"></div>"
+}
+```
+
+```javascript
+// Step Loaded 핸들러 — getElementById 로 DOM 잡고 지도를 실제로 렌더 (로드는 StyleURLs 가 끝냄)
+var el = document.getElementById('naverMap');
+var lat = _c.activeSector.Latitude;
+var lng = _c.activeSector.Longitude;
+var map = new naver.maps.Map(el, { center: new naver.maps.LatLng(lat, lng), zoom: 16 });
+new naver.maps.Marker({ position: new naver.maps.LatLng(lat, lng), map });
+```
+
+### 예시 C — QR 코드 (StyleURLs + Step Loaded 렌더)
+
+```jsonc
+// 라이브러리: Scenario.StyleURLs 에 등록
+{ "Scenario": { "StyleURLs": ["https://cdn.jsdelivr.net/npm/qrcode@1.4.4/build/qrcode.min.js"] } }
+
+// Embed control
+{
+  "ControlType": "Embed",
+  "Id": "f_qr",
+  "ControlDefaultName": "QrEmbed", "ControlName2": "QrEmbed",
+  "Caption": "",
+  "Width":  { "SizeValue": "200", "SizeUnit": "px", "MatchText": false },
+  "Height": { "SizeValue": "200", "SizeUnit": "px", "MatchText": false },
+  "Embed": "<div id=\"qrcode\"></div>"
+}
+```
+
+```javascript
+// Step Loaded 핸들러 — getElementById 로 DOM 잡고 QR 을 실제로 렌더
+QRCode.toDataURL(data, function(err, url) {
+  document.getElementById('qrcode').innerHTML = '<img src="' + url + '">';
+});
+```
+
+## 숨김 style-only Embed
+
+CSS 주입 용도 — Width/Height 0px 로 보이지 않게.
+
+```jsonc
+{
+  "ControlType": "Embed",
+  "Caption": "",
+  "Width":  { "SizeValue": "0", "SizeUnit": "px", "MatchText": false },
+  "Height": { "SizeValue": "0", "SizeUnit": "px", "MatchText": false },
+  "Embed": "<style>.custom-class { color: red; }</style>"
+}
+```
+
+## 함정
+
+- **`{=Field}` 디스플레이 토큰 금지 (`[embed-bind]`)** — Embed raw HTML 안에서는 `{=Field}` 가 치환되지 않고 문자 그대로 노출된다. 섹터 값은 `{%return Load.sector.Field; %}` (LoadScript 토큰) 로 바인딩 — DC 그룹 안의 Embed 면 그 행의 섹터가 `Load.sector` 로 주입됨.
+- **`<script>` 직접 삽입 금지** — 외부 라이브러리는 **`Scenario.StyleURLs` 등록을 우선**(정적 URL). `f.Script.load()` 는 동적 URL 등 부득이한 경우로 한정.
+- **`Caption: ""` 반드시 빈 문자열** — 스키마 const 강제. ControlDefaultName 같은 값을 두면 화면에 그대로 출력됨.
+- DOM 조작은 **부모 Step 의 Loaded/Init 이벤트** 에서. Embed 본체에는 별도 이벤트 없음.
+- 🔴 **로드만 하고 렌더를 빼먹지 말 것 (`[embed-render]`)** — `StyleURLs`/`f.Script.load` 로 라이브러리를 불러오는 것만으로는 canvas/빈 div 에 아무것도 안 그려진다. `<canvas>`/빈 `<div id=…>` Embed 는 반드시 host Step 의 `Loaded` 핸들러에서 `document.getElementById(...)` 로 잡아 `new Chart()`/`new naver.maps.Map()` 등 **렌더 코드를 직접 실행**해야 한다. `checkEmbedRender()` 가 누락을 차단.
+- **`Tab` 컨트롤 내부 LinkedStep 에는 Embed 금지 (`[tab-embed]`)** — 탭 내부 Step 은 Step 이벤트(`Init`/`Loaded`)가 미실행이라 DOM 초기화 시점을 잡을 수 없다 (예: 통계 탭의 차트). 빈 영역만 그려지거나 차트가 안 뜬다. `Items[].LinkedStepId` 로 띄우는 Step 의 Contents 에 Embed 가 있으면 `checkTabLinkedStepEmbed()` 가 거부. Embed 가 필요한 화면은 **탭이 아닌 별도 Step** 으로 분리. ([control/tab.md](tab.md) "탭 내부 LinkedStep 에는 Embed 컨트롤 금지" 참조.)
+- 외부 라이브러리 callback 은 Events 섹션에 **동일한 이름** 으로 등록 필수 (불일치 시 콜백 미호출).
+- `Loaded` 이벤트로 진입하는 Step 으로 뒤로 가는 BottomButton 은 `Prev_ReStart` 사용 — 일반 `Prev` 면 차트/지도가 재초기화 안 됨.
+- 지도: 한국 시나리오 → 네이버지도 JavaScript API, 해외 → Google Maps. iframe 방식은 간단 표시용으로만 (해외).
+- div/canvas 의 id 는 시나리오 내 **유니크** 해야 함 (DOM querySelector 충돌 방지).

package/contract-data/schema/v1/control/embed.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/embed.schema.json",
+  "title": "Embed",
+  "description": "HTML 태그를 직접 화면에 삽입하는 컨트롤. Embed 속성에 raw HTML 문자열을 두면 그대로 렌더된다. 외부 라이브러리(Chart/지도/QR 등) 연동 시 유니크한 id 의 <div>/<canvas> 를 두고 외부 라이브러리 URL 은 Scenario.StyleURLs 배열에 등록(권장 — 진입 시 자동 로드; 동적 URL 등 부득이한 경우만 f.Script.load() 사용). ★ 로드 ≠ 렌더([embed-render]): 라이브러리 로드만으로는 안 그려진다 — canvas/빈 컨테이너 Embed 는 반드시 host Step 의 Loaded 핸들러에서 document.getElementById() 로 DOM 을 잡아 new Chart()/new naver.maps.Map() 등 렌더 코드를 직접 실행해야 한다. ★ Tab 컨트롤 내부 LinkedStep 에는 Embed 금지([tab-embed]) — 탭 내부 Step 은 Step 이벤트가 미실행이라 초기화 시점을 못 잡음. ★ Caption 은 반드시 빈 문자열 (Embed 본체에 표시되므로 ControlDefaultName 같은 내부명을 두면 그대로 출력됨).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType", "Embed"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "Embed" },
+        "Caption": {
+          "type": "string",
+          "const": "",
+          "description": "★ 반드시 빈 문자열 — Embed 는 화면에 직접 그려지므로 Caption 값이 그대로 노출된다."
+        },
+        "Embed": {
+          "type": "string",
+          "description": "삽입할 raw HTML 문자열. <video>/<iframe>/<canvas>/<div>/<style> 등. ★ <script></script> 직접 삽입 불가 — 외부 라이브러리 URL 은 Scenario.StyleURLs 배열에 등록(권장). ★ 섹터 값 바인딩은 {%return Load.sector.Field; %} (LoadScript 토큰) — {=Field} 는 Embed 안에서 치환되지 않고 그대로 노출됨([embed-bind] 차단). Load.sector 는 조상 DC 그룹(UseDataConnection:true) 아래에서만 그 행의 섹터를 가리킴 — DC 밖이면 조용히 빈 문자열([embed-bind] 차단). 외부 라이브러리 연동 시 div/canvas 에 유니크한 id 부여 → Step Loaded 에서 document.getElementById() 로 DOM 잡고 라이브러리 호출."
+        },
+        "LoadScript": {
+          "type": "string",
+          "description": "(선택) 컴포넌트 로드 직전 스크립트. DOM 접근은 Step Loaded 에서 처리하는 게 일반적이라 통상 미사용."
+        }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/control/image-box.md

@@ -0,0 +1,237 @@
+# ImageBox
+
+이미지 표시/업로드 컨트롤. `ImageBoxType` 으로 두 모드 분기.
+
+## 스키마
+
+`control/image-box.schema.json` — `controlBase` + 분기 키 (`ControlType="ImageBox"`, `ImageBoxType`, `ViewGroup`, `EditGroup`).
+
+## ImageBoxType (제한)
+
+| 값 | 동작 | 필수 프로퍼티 |
+|---|---|---|
+| `"View"` | 읽기 전용 표시 | `ViewGroup` |
+| `"Edit"` | 업로드/촬영 + 표시 | `ViewGroup` (placeholder) + `EditGroup` (FlexFile 저장) |
+
+> **원리**: Edit 업로드 → 파일키가 `EditGroup.FlexKey.ckey` 컬렉션 필드에 저장. View 에서 동일 `ImageSrcType: "FlexFile"` + 동일 `FlexKey`/`ckey` 값으로 표시.
+
+## ImageSrcType (ViewGroup.ImageSrcType)
+
+| 값 | 키 | 의미 |
+|---|---|---|
+| `"FlexFile"` | `FlexKey` + `ckey` | Edit 업로드 이미지 표시 (둘은 같은 값) |
+| `"Url"` | `ImageUrl` | 외부 URL. `{=ImageField}` 바인딩 가능 |
+| `"Base64"` | `ImageUrl` | Base64 인코딩 인라인 |
+| `"Upload"` | — | **Edit 모드 전용** — `ViewGroup` 의 업로드 placeholder. `EditGroup` 와 짝 |
+
+## 시나리오 생성 시 (AI 생성 스켈레톤)
+
+**AI 가 시나리오를 생성할 때는 데이터 바인딩 메타(`ViewGroup` / `EditGroup`)를 생략해도 된다.** FlexFile 키 / 카테고리 필드명 / SharedTarget 등은 스튜디오 또는 사용자가 사후 설정한다.
+
+```jsonc
+// AI 생성 — View 스켈레톤 (데이터 미설정)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ControlDefaultName": "ImgView1",
+  "ControlName2": "ImgView1",
+  "Caption": "ImgView1",
+  "Id": "f_41",
+  "Width":  { "SizeValue": "80",  "SizeUnit": "px" },
+  "Height": { "SizeValue": "80",  "SizeUnit": "px" },
+  "isColumnCtrl": false
+}
+```
+
+```jsonc
+// AI 생성 — Edit 스켈레톤 (데이터 미설정)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ControlDefaultName": "ImgUpload1",
+  "ControlName2": "ImgUpload1",
+  "Caption": "ImgUpload1",
+  "Id": "f_42",
+  "Width":  { "SizeValue": 100,   "SizeUnit": "%" },
+  "Height": { "SizeValue": "200", "SizeUnit": "px" },
+  "isColumnCtrl": false
+}
+```
+
+> **원칙**: AI 는 `ImageBoxType` 만 결정하고 데이터 메타는 두지 않는다. 다만 `ViewGroup` / `EditGroup` 을 **굳이 작성한다면** 아래 정식 예시처럼 **유효한 형태로** (ImageSrcType 별 필수 키를 채워서) 작성해야 한다 — 빈 객체 / 누락 키는 schema 차단.
+
+## 예시 — View 모드 (FlexFile)
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": "PhotoUrl",
+    "ckey": "PhotoUrl"
+  },
+  "Width":  { "SizeValue": "80", "SizeUnit": "px" },
+  "Height": { "SizeValue": "80", "SizeUnit": "px" },
+  "ControlDefaultName": "ImgView",
+  "ControlName2": "ImgView",
+  "Caption": "ImgView",
+  "Id": "f_41",
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — View 모드 (Url)
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "{=ImageField}"
+  },
+  "ControlDefaultName": "ImgUrl",
+  "ControlName2": "ImgUrl",
+  "Caption": "ImgUrl",
+  "Id": "f_42",
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — Edit 모드
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ViewGroup": {
+    "ImageSrcType": "Upload"
+  },
+  "EditGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": { "ckey": "PhotoUrl", "Name": "" },
+    "Module": "FlexFile"
+  },
+  "UseCondition": "false",
+  "UseMultiData": "false",
+  "UseEvents": "false",
+  "Events": {},
+  "Width":  { "SizeValue": 100,    "SizeUnit": "%" },
+  "Height": { "SizeValue": "200",  "SizeUnit": "px" },
+  "ControlDefaultName": "ImgUpload",
+  "ControlName2": "ImgUpload",
+  "Caption": "ImgUpload",
+  "Id": "f_43",
+  "isColumnCtrl": false
+}
+```
+
+> **Edit 모드 필수**: `ViewGroup`(`ImageSrcType: "Upload"`) + `EditGroup`(FlexFile 저장) 둘 다. `UseCondition`/`UseMultiData`/`UseEvents`/`Events` 함께 작성하는 것이 실 샘플 패턴 (값은 문자열 `"false"` 도 통과).
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/imageBoxEvents` 적용. `ImageEventOrder` 에 `Click` 만. EventOrder ↔ 핸들러 일치 강제.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "ImageEventOrder": ["Click"],
+    "Click": "ON_IMAGE_CLICK_E"
+  }
+}
+```
+
+## FlexKey 형태
+
+| 모드 | 형태 | 비고 |
+|---|---|---|
+| `View` | string (필드명) | `ckey` 와 동일 값으로 동시에 작성 |
+| `Edit.EditGroup` | `{ "ckey": "...", "Name": "" }` | `ckey` 가 저장 대상 필드명 |
+
+## SharedTarget
+
+`"tenant"` (테넌트 공유, 일반) / `"user"` (사용자 전용) / `"global"` (전역 공유). 실 샘플 대부분 `"tenant"`.
+
+## `UseDefaultValue` — 기본(폴백) 이미지
+
+`UseDefaultValue` 는 **단일 boolean 키**(`engine const K.USE_DEFAULTVALUE='UseDefaultValue'`) 지만 `ImageBoxType` 별로 의미가 다르다. property-data.js 가 두 개의 UI 토글(`createUseDefault` / `createUseDefaultView`)로 노출하지만 둘 다 같은 키에 기록.
+
+| ImageBoxType | 토글 UI 위치 | UseDefaultValue=true 효과 | 추가 키 |
+|---|---|---|---|
+| `Edit` | `createUseDefault` (id `UseDefault`) — Edit 그룹 안 | EditGroup 업로드 실패/미설정 시 `ViewGroup` 의 이미지를 placeholder 로 표시 ([imagebox.js:42-45](public/engine/control/imagebox.js#L42)) | `ViewGroup` (기존) |
+| `View` | `createUseDefaultView` (id `UseDefaultView`) — View 그룹 안 | `ViewGroup` 의 FlexFile/Base64 로드가 비어있을 때 `DefaultViewGroup` 의 이미지를 fallback 으로 표시 | `DefaultViewGroup` 추가 |
+
+> **View 모드의 토글 표시 조건** (property-data.js line 11780): `ViewGroup.ImageSrcType ∈ { "FlexFile", "Base64" }` 일 때만 스튜디오 프로퍼티 패널에 노출. `Url` 일 때는 표시 안 됨 (URL 은 외부 리소스라 fallback 의미 약함).
+
+### `DefaultViewGroup` 형태
+
+`ViewGroup` 과 **완전히 동일한 shape** — `_base.schema.json#/$defs/imageBoxViewGroup` 그대로 재사용. 즉 `ImageSrcType` 분기에 따라 `FlexKey`/`ckey`/`ImageUrl` 등이 같은 규약으로 채워진다.
+
+```jsonc
+// View 모드 + UseDefaultValue=true (운영 메타 예 — AI 생성에는 두지 말 것)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": "PhotoUrl",
+    "ckey":    "PhotoUrl"
+  },
+  "UseDefaultValue": true,
+  "DefaultViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "/imagesCommon/avatar-placeholder.png"
+  },
+  "Id": "f_60"
+}
+```
+
+→ `_collections` 에서 `PhotoUrl` 이 비어있거나 FlexFile 다운로드가 실패하면 `DefaultViewGroup` 의 placeholder URL 이 대신 표시.
+
+### Edit 모드 — `UseDefaultValue=true` 만 두는 케이스
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "/imagesCommon/upload-placeholder.png"
+  },
+  "EditGroup": {
+    "ImageSrcType": "FlexFile",
+    "FlexKey": { "ckey": "PhotoUrl", "Name": "" },
+    "Module":  "FlexFile"
+  },
+  "UseDefaultValue": true,
+  "Id": "f_61"
+}
+```
+
+→ 업로드 전에는 `ViewGroup` 의 placeholder URL 이 보이고, 업로드 후에는 그 자리에 업로드한 이미지가 표시. Edit 모드에서는 `DefaultViewGroup` 을 두지 않는다 — `ViewGroup` 자체가 placeholder 역할.
+
+### ★ AI 생성 정책
+
+- `UseDefaultValue` 는 **boolean strict** (CHECKBOX 진실원본). 문자열 `"true"`/`"false"` 금지.
+- `DefaultViewGroup` 은 **AI 생성 시 미포함** — 운영에서 placeholder 이미지를 정한 다음 사용자가 수동 설정. AI 가 굳이 placeholder 경로를 추측하지 않는다. ([control.md §AI 샘플 생성 금지 키](../control.md#ai-critical) 단일 진실원본 표 등재 — `AI_GEN_STRICT=1` 시 validate.mjs `[ai-gen]` 태그 차단.)
+- AI 생성 스켈레톤 단계에서는 둘 다 생략 권장. ImageBoxType 만 결정.
+
+## Edit ↔ View 연동
+
+- Edit 업로드 시 → `EditGroup.FlexKey.ckey` 컬렉션 필드에 파일키 저장.
+- View 에서 표시할 때 → `ImageSrcType: "FlexFile"` + 같은 `FlexKey`/`ckey` 값.
+- View 에서 `ImageSrcType: "Url"` 로 두면 FlexFile 파일키는 표시 못 함 — 외부 URL 만.
+
+## 함정
+
+- `ControlName2` 누락 = 런타임 에러. `ControlDefaultName` 과 같은 값.
+- `isColumnCtrl: false` 항상 명시 (Sheet 컬럼 모드는 OtherControl).
+- AI 생성 단계에서는 `ViewGroup` / `EditGroup` 을 생략해도 schema 통과 (스켈레톤). 운영에 투입하려면 사후 설정 필수.
+- Edit 모드 운영 시 `ViewGroup` 누락 → 업로드 후 표시 영역 비어 있음. `ImageSrcType: "Upload"` 로 placeholder 명시.
+- Edit 모드 `EditGroup.FlexKey` 는 **객체** (`{ ckey, Name }`), View 모드 `FlexKey` 는 **string**. 혼동 주의.
+- `Ckeys` 미사용 — 데이터 바인딩은 `ViewGroup.ckey` / `EditGroup.FlexKey.ckey` 로 처리 (별도 `Ckeys` 배열은 두지 않는다).

package/contract-data/schema/v1/control/image-box.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/image-box.schema.json",
+  "title": "ImageBox",
+  "description": "이미지 표시/업로드 컨트롤. ImageBoxType=View → ViewGroup 으로 이미지 표시. ImageBoxType=Edit → ViewGroup(=업로드 placeholder) + EditGroup(FlexFile 저장) 둘 다 권장. Edit 업로드 → 파일키가 EditGroup.FlexKey.ckey 컬렉션 필드에 저장 → View 에서 ImageSrcType='FlexFile' + 동일 FlexKey/ckey 로 표시. **AI 시나리오 생성 시**: ViewGroup/EditGroup 등 데이터 바인딩 메타는 생략 가능 (스튜디오/사용자가 사후 설정). 단 ViewGroup/EditGroup 을 작성한다면 그 안의 ImageSrcType 별 필수 키는 강제.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType":  { "const": "ImageBox" },
+        "ImageBoxType": {
+          "type": "string",
+          "enum": ["View", "Edit"],
+          "description": "View=읽기전용 이미지 표시. Edit=업로드/촬영 + 표시."
+        },
+        "ViewGroup": { "$ref": "_base.schema.json#/$defs/imageBoxViewGroup" },
+        "EditGroup": { "$ref": "_base.schema.json#/$defs/imageBoxEditGroup" },
+        "UseDefaultValue": {
+          "type": "boolean",
+          "default": false,
+          "description": "기본(폴백) 이미지 사용 여부. ★ 단일 키지만 ImageBoxType 별로 의미가 다름: (1) ImageBoxType='Edit' → true 면 EditGroup 업로드 전/실패 시 ViewGroup 의 이미지를 placeholder 로 표시 (property-data createUseDefault, 토글 UI 'UseDefault'). (2) ImageBoxType='View' → true 면 DefaultViewGroup 활성 — ViewGroup 의 FlexFile/Base64 로드 실패 시 fallback (property-data createUseDefaultView, 토글 UI 'UseDefaultView', 표시 조건: ViewGroup.ImageSrcType ∈ {'FlexFile','Base64'}). engine const K.USE_DEFAULTVALUE='UseDefaultValue' — 프로퍼티 EDITOR_CTRL.CHECKBOX, boolean strict."
+        },
+        "DefaultViewGroup": {
+          "$ref": "_base.schema.json#/$defs/imageBoxViewGroup",
+          "description": "기본 이미지 정의 — ImageBoxType='View' + UseDefaultValue=true 조합에서 fallback 으로 표시될 이미지. shape 은 ViewGroup 과 동일 ($defs/imageBoxViewGroup). UseDefaultValue=true 면 사용자 수동 설정으로 채워짐. ★ AI 생성 시 미포함 — 운영 사후 설정 전용."
+        },
+        "UseCondition": { "type": "boolean", "description": "조건부 동작 사용. Edit 모드 샘플은 문자열 'false' 도 허용." },
+        "UseMultiData": { "type": "boolean", "description": "다중 이미지 사용. Edit 모드 샘플은 문자열 'false' 도 허용." },
+        "UseEvents":    { "type": "boolean", "description": "이벤트 사용. Edit 모드 샘플은 문자열 'false' 도 허용." },
+        "Events":       { "$ref": "_base.schema.json#/$defs/imageBoxEvents" }
+      },
+      "required": ["ImageBoxType"]
+    },
+    {
+      "$comment": "ImageBoxType='View' + UseDefaultValue=true → DefaultViewGroup 권장. 운영 메타에 종종 누락 — schema 강제 안 함 (가이드 차원).",
+      "if": {
+        "properties": {
+          "ImageBoxType":    { "const": "View" },
+          "UseDefaultValue": { "const": true }
+        },
+        "required": ["ImageBoxType", "UseDefaultValue"]
+      },
+      "then": {}
+    }
+  ]
+}