@flextudio/scenario 0.1.0

package/contract-data/schema/v1/mockup-data.md

@@ -0,0 +1,186 @@
+# 목업 데이터 (Mockup Data)
+
+스킬 생성 모드(외부 Service/API 차단)에서 화면이 그릴 **유일한 데이터 출처**. 시작 Step (`StartSteps[0]`) 의 `Events.Init` 핸들러가 `f.Collection.addSector({...}, '<카테고리>')` 로 카테고리 섹터 데이터를 박는 방식이다.
+
+> **이 데이터는 `DataSource` 가 아니다.** 시나리오 `DataSources` 와 무관하게, 카테고리(`scenario.Panel.Category` 정의 또는 `DataConnection.CategoryName` 명시) 의 **섹터 누적**으로 표현된다. 단순 선택지 목록(Combo/Radio 옵션 등)이 필요하면 [Data Sources](data-sources.md) 의 `Fixed`/`Grid` 를 사용한다.
+
+## 큰 그림
+
+```
+[1] 그룹/컨트롤이 카테고리 사용
+    UseDataConnection: true + DataConnection.CategoryName='CtgX'
+       ↓
+[2] 시작 Step.Events.Init 가 카테고리에 mock 섹터 N건 박음
+    f.Collection.addSector({...키:값...}, 'CtgX')
+       ↓
+[3] DataConnection 으로 자동 반복 렌더링 — 같은 컨트롤이 섹터 수만큼 반복
+```
+
+`[mock-init]` cross-check 가 이 정합을 강제 — 시나리오에서 사용되는 카테고리(`DataConnection.CategoryName`) 에 대해 시작 Step 의 Init 핸들러가 `addSector` 호출을 1회 이상 포함해야 통과. `LinkedEvent` 로 위임된 보조 핸들러도 함께 추적된다.
+
+> **예외 — `DataUsage:"new"` (신규입력) 는 Init mock 불필요.** 신규입력 그룹은 **진입 시 빈 섹터가 자동 생성**되어 그 섹터에 입력값이 바인딩되므로(data-objects.md §1.2), 시작 Step Init 에서 따로 `addSector` 를 박지 않아도 된다. `[mock-init]` 도 `new` 로만 쓰인 카테고리는 요구 대상에서 제외한다. 단, **같은 카테고리가 어딘가에서 `query`/`update`/`detail`/`default` 등 읽기 용도로도 쓰이면** 그 읽기 화면이 그릴 데이터가 필요하므로 Init mock 이 여전히 필요하다.
+
+## ★ 짝 규칙 — DC 그룹 하위 데이터 항목은 콜렉션키 바인딩 필수
+
+`[mock-init]` 이 강제하는 건 **정방향**(카테고리 → Init 에서 mock 섹터 박기)뿐이다. 그 짝이 되는 **역방향** 도 반드시 지켜야 한다:
+
+> **mock 을 박은 DataConnection 그룹 하위에서, 데이터가 연결되어야 하는 항목들은 콜렉션키(Ckey)가 지정되어 있어야 한다.**
+
+addSector 로 섹터에 넣은 필드(`fName`, `fPrice` 등)는 그룹 하위 컨트롤이 **콜렉션키로 바인딩**해야 화면에 그려진다. 바인딩 키 없이 정적 텍스트(`Label.labeltext`, 정적 `Caption`)만 두면 **mock 데이터는 들어가지만 화면에는 고정 텍스트만 나오고 데이터는 죽는다** (DC 그룹이 섹터 수만큼 복제되어도 모든 카드가 똑같은 정적 문구를 반복).
+
+| 항목 유형 | 데이터 표시/입력 시 채워야 할 콜렉션키 |
+|---|---|
+| `Label` (값 표시) | `LabelType: "LabelCKey"` + `LabelCKey: "<섹터 필드명>"` (정적 라벨은 `labeltext` 그대로 OK) |
+| `InputText` / `InputNumber` / `InputMask` / `InputDate` / `MultiInputBox` | `Ckeys: ["<섹터 필드명>"]` (update/new 그룹에서 입력값 ↔ 섹터 매핑) |
+| `Combo` / `Search` | `Ckeys` + `SaveValueKey` / `CtrlDisplayCkey` (rules.md §5.5) |
+| `CheckBox` / `RadioBox` | `Ckeys` |
+| `Button` (값 표시) | `ButtonValueCKey` |
+
+- 바인딩 대상은 **그 섹터에서 실제로 보여줄/입력받을 필드들** — 카드 안의 장식용 정적 라벨까지 전부 바꾸라는 뜻은 아니다. 데이터가 흘러야 하는 항목만 콜렉션키를 채운다.
+- 콜렉션키를 가진 컨트롤은 조상 어딘가에 `UseDataConnection:true` 그룹이 있어야 한다 (`[bind]` / rules.md §5.1).
+- 어떤 콜렉션키도 안 쓰는 순수 정적 UI 라면 애초에 DataConnection / mock 을 두지 말 것 → `[proto]` 모드(`Ckeys`/`DataConnection`/`LabelCKey` 금지).
+
+## 기본 예시
+
+```jsonc
+// 시작 Step
+"Step1": {
+  "Events": {
+    "UseEvents": true,
+    "StepEventOrder": ["Init"],
+    "Init": "InitMockData"
+  },
+  "Contents": [
+    {
+      "ContentsType": "Group",
+      "UseDataConnection": true,
+      "DataConnection": { "TargetType": "category", "DataUsage": "query", "CategoryName": "CtgItemList" },
+      "Contents": [
+        // 카드 안 데이터 항목은 addSector 가 박은 필드(fName/fPrice)를 콜렉션키로 바인딩.
+        { "ControlType": "Label", "LabelType": "LabelCKey", "LabelCKey": "fName",  /* ... */ },
+        { "ControlType": "Label", "LabelType": "LabelCKey", "LabelCKey": "fPrice", /* ... */ }
+        // ✗ LabelType:"labeltext" + labeltext:"사과" 로 두면 모든 카드가 '사과' 만 반복 — mock 이 죽음.
+      ]
+    }
+  ]
+}
+
+// scenario.Events — 한 카테고리의 모든 섹터는 Script 액션 하나에 모은다.
+//   addSector 호출마다 \n 으로 줄바꿈하고, 객체 필드도 \n 들여쓰기로 (Ctrl+K+F 수준 가독성).
+//   섹터 1건당 {Action:Script} 를 따로 만들지 말 것.
+"Events": {
+  "InitMockData": [
+    {
+      "Action": "Script",
+      "Script": "f.Collection.addSector({\n  fId: 'i1',\n  fName: '사과',\n  fPrice: 1000\n}, 'CtgItemList');\nf.Collection.addSector({\n  fId: 'i2',\n  fName: '바나나',\n  fPrice: 1500\n}, 'CtgItemList');"
+    }
+  ]
+}
+```
+
+> 카테고리 자체는 `Panel.Category` 정의 또는 `DataConnection.CategoryName` 명시로 자유롭게 만들 수 있다 — 카테고리 생성에는 제한 없음.
+
+## 카테고리 리셋 패턴 (재진입 안전)
+
+`Init` 이 여러 번 도는 경우(`moveToFirst` 등) 섹터가 중복으로 박힐 수 있으므로 리셋 + 재생성 순서를 권장한다.
+
+```jsonc
+"STEP1_Init_E": [
+  { "Action": "Script", "Script": "f.Collection.removeCategory('CtgItemList');\nf.Collection.createCategory('CtgItemList');\n_c.CtgItemList.addSector({ Title:'A' });\n_c.CtgItemList.addSector({ Title:'B' });" }
+]
+```
+
+> **CRITICAL** — `_c.CtgX[0].set(...)` 호출 전에 반드시 `removeCategory + createCategory` 선행. 없으면 TypeError. (system-prompt-v2.md §4644)
+
+## `[script-allow]` — Init 핸들러 제한
+
+Init 은 mock 섹터를 박는 단계이므로 화면 갱신/푸시/외부 스크립트 로드 호출이 차단된다.
+
+| 차단되는 호출 | 사유 |
+|---|---|
+| `Current.step.reload(WithAnimation)` | DOM 아직 안 그려졌음 — Loaded 이후에서 호출 |
+| `f.Content(fid).reload(WithAnimation)` | 동일 |
+| `f.Event(...).runNext()` / `.break()` | Init 은 단순 mock 생성만 |
+| `f.MessageBox(...)` | 모달 다이얼로그 표시는 Loaded 이후에서 |
+| `f.Script.load(...)` | 외부 라이브러리 로드는 Loaded 또는 별도 이벤트 |
+
+허용 호출: `f.Collection.addSector` / `_c.<Cat>.addSector` / `_c.<Cat>[*].set(...)` / `f.Date()` 등.
+
+## Tab + LinkedStep 패턴
+
+탭이 있는 부모 Step 의 Init 에서 모든 샘플 데이터를 한 번에 로딩. LinkedStep 의 Init 에 두면 탭 전환마다 `removeCategory + createCategory` 가 다시 돌아 데이터가 초기화된다 (LinkedStep 의 Step 이벤트는 미실행이므로 부모 Step 에 박는 것이 표준).
+
+```jsonc
+// 부모 Step (탭이 있는 Step) — 모든 카테고리 한 번에 로딩
+"Step1": {
+  "Events": { "UseEvents": true, "StepEventOrder": ["Init"], "Init": "InitAllMock" }
+}
+// LinkedStep 들은 Events: [] (탭이 자체적으로 그릴 데이터는 부모 Step 의 Init 결과를 공유)
+```
+
+## `[proto]` 모드와의 관계
+
+DataSources 도 비어있고 Init 에도 `f.Collection.addSector` 가 전혀 없다면 진짜 정적 UI 목업 — `[proto]` 모드가 발동해 `Ckeys` / `DataConnection` / `LabelCKey` 사용을 금지한다. 표준 흐름은 [mock-init] + DC 반복 렌더링이므로 보통은 Init 에서 mock 섹터를 박는 쪽으로 작성한다.
+
+## Script 본문 표기 규칙
+
+`Action: "Script"` 의 `Script` 값은 **한 줄 JSON 문자열로 박고 줄바꿈은 `\n` 이스케이프**로 표현한다. JS 문자열 `+` 연결로 여러 줄에 걸쳐 두지 말 것.
+
+```jsonc
+// ✓ 정상 — 한 줄 + \n
+{ "Action": "Script", "Script": "f.Collection.removeCategory('CtgX');\nf.Collection.createCategory('CtgX');\n_c.CtgX.addSector({ Title:'A' });" }
+
+// ✗ 잘못 — JS + 연결 (JSON 파서가 받을 수 없음)
+{ "Action": "Script", "Script":
+  "f.Collection.removeCategory('CtgX');" +
+  "f.Collection.createCategory('CtgX');"
+}
+```
+
+### addSector 작성 규칙 (★ 필수)
+
+**1. 인자 순서 — `addSector(객체, '카테고리')`**
+첫 인자는 섹터 데이터 **객체**, 둘째 인자는 **카테고리명 문자열**이다. 순서를 뒤집은 `addSector('카테고리', {...})` 는 틀린 호출 — `[mock-init]` 이 카테고리를 인식하지 못해 "addSector 된 카테고리: (없음)" 으로 판정되고, 실제로도 섹터가 안 박혀 화면에 데이터가 안 나온다.
+
+```js
+// ✓ f.Collection.addSector({ orderNo: 'ORD-001' }, 'CtgOrderList')
+// ✗ f.Collection.addSector('CtgOrderList', { orderNo: 'ORD-001' })   ← 인자 역전, 동작 안 함
+```
+
+**2. 카테고리 단위로 묶기 — 섹터마다 액션을 쪼개지 말 것**
+한 카테고리에 박을 섹터가 여러 건이어도 **Script 액션 하나** 안에 `addSector` 호출들을 `\n` 으로 이어 담는다. 섹터 1건당 `{ "Action": "Script" }` 를 따로 만들면 안 된다. **카테고리가 2개면 Script 액션 2개** — 카테고리당 하나씩.
+
+**3. 줄바꿈/들여쓰기 가독성 (Ctrl+K+F 수준)**
+`addSector` 호출 사이는 `\n`, 객체 필드는 `\n  ` 들여쓰기로 한 필드씩 — 사람이 보기 쉽게 포맷한다. 여러 `addSector` 를 한 줄에 `;` 로 다닥다닥 붙이지 말 것.
+
+```jsonc
+// ✓ 정상 — 카테고리 2개 → Script 액션 2개, 각 액션 안에서 줄바꿈/들여쓰기
+"Init": [
+  {
+    "Action": "Script",
+    "Script": "f.Collection.addSector({\n  fOrderNo: 'ORD-001',\n  fOrderDate: '2024-01-15',\n  fTotalAmt: '150000'\n}, 'CtgOrder');\nf.Collection.addSector({\n  fOrderNo: 'ORD-002',\n  fOrderDate: '2024-01-16',\n  fTotalAmt: '85000'\n}, 'CtgOrder');"
+  },
+  {
+    "Action": "Script",
+    "Script": "f.Collection.addSector({\n  fOrderNo: 'ORD-001',\n  fItemName: '노트북',\n  fQty: '1'\n}, 'CtgOrderItem');\nf.Collection.addSector({\n  fOrderNo: 'ORD-002',\n  fItemName: '키보드',\n  fQty: '1'\n}, 'CtgOrderItem');"
+  }
+]
+
+// ✗ 잘못 — 섹터마다 Script 액션을 쪼갬 (한 줄에 ; 로 붙이거나 액션 7개로 분산)
+"Init": [
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-001',...}, 'CtgOrder');" },
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-002',...}, 'CtgOrder');" },
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-001',...}, 'CtgOrderItem');" }
+]
+```
+
+## 함정
+
+- **`DataSourceType: "Script"` 는 존재하지 않음** — 동적으로 만드는 화면 데이터는 카테고리 섹터로 표현한다.
+- 카테고리에 mock 섹터를 박지 않으면 컨트롤이 DC 로 반복되어도 화면에 아무것도 안 그려짐 → `[mock-init]` cross-check fail. **단 `DataUsage:"new"` 신규입력 그룹은 빈 섹터가 자동 생성되므로 Init mock 불필요** — 빈 입력 폼을 위해 `addSector({필드:''}, ...)` 로 빈 섹터를 억지로 박지 말 것.
+- **반대로** mock 은 박았는데 DC 그룹 하위 데이터 항목이 콜렉션키 없이 정적 텍스트(`labeltext` / 정적 `Caption`)뿐이면, 모든 카드가 같은 고정 문구를 반복하고 mock 데이터는 화면에 안 나옴 → 위 ★ 짝 규칙 위반. 데이터가 흘러야 하는 항목은 `LabelCKey` / `Ckeys` / `SaveValueKey` 등으로 바인딩.
+- `moveToFirst` 로 시작 Step 으로 돌아가면 Init 이 재실행되어 사용자 입력이 날아갈 수 있다 — 카테고리 리셋 패턴 필요. (system-prompt-v2.md §4730)
+- LinkedStep 의 Init 에 mock 을 박지 말 것 — Step 이벤트가 미실행이라 데이터가 안 들어감.
+- `Script` 값에 raw newline 박지 말 것 — JSON 파싱 실패. 줄바꿈은 항상 `\n` 이스케이프.
+- **`addSector` 인자 순서 역전** — `addSector('카테고리', {...})` 는 틀림. 항상 `addSector({...}, '카테고리')` (객체 먼저, 카테고리 마지막). 역전하면 `[mock-init]` 이 카테고리를 못 잡아 통과 실패 + 섹터도 안 박힘. (위 "addSector 작성 규칙 §1")
+- **섹터마다 Script 액션을 쪼개지 말 것** — 한 카테고리의 여러 섹터는 Script 액션 하나에 `\n` 으로 모은다. 카테고리 수만큼만 Script 액션을 둔다 (카테고리 2개 → 액션 2개). 섹터 N건을 액션 N개로 분산하면 가독성·구조 모두 나쁘다. (위 "addSector 작성 규칙 §2")

package/contract-data/schema/v1/naming-objects.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/naming-objects.schema.json",
+  "title": "Naming Objects",
+  "description": "컬렉션 식별자 (Ckey / CategoryName) 의 명명 제약 카탈로그. AI 메타 생성 시 시스템 예약어 / JS 예약어 / JS 빌트인 충돌을 schema 레벨에서 강제 차단. 상세 규칙은 runtime/v1/collection/naming.md, runtime/v1/collection/sector.md §6 참조.",
+
+  "$defs": {
+    "categoryReservedKeys": {
+      "$comment": "isInvalidCategoryName() 의 차단 키 목록. 런타임이 categoryBridge 생성을 거부함. ckey 측에서도 Sector prototype 메서드(activate/select/unSelect/setStatus) 와 충돌하므로 동일 enum 을 ckey 차단에도 합친다.",
+      "enum": [
+        "outerSector", "outerBlock", "collection", "status", "category",
+        "suids", "keys", "active", "activeSector", "last", "lastSectors",
+        "displayed", "added", "updated", "selected", "deleted",
+        "isPrototypeOf", "propertyIsEnumerable", "toLocaleString",
+        "activate", "unActivate", "select", "unSelect"
+      ]
+    },
+
+    "sectorReservedKeys": {
+      "$comment": "Sector 인스턴스의 시스템 게터 이름 (public/engine/common/collection.js / const.js). 컬렉션키로 사용 시 setter 가 debug 모드에서 에러 출력 + 정상 모드에서도 값이 반영되지 않는다 (COLLECTION_ESCAPE). _SUID 는 시스템 등록 키 — Sector 인스턴스 속성으로 직접 두면 동작 깨지지만, Panel.Collection.Ckeys 의 시스템 등록 슬롯에는 반드시 포함되어야 하므로 ckeyWithSuid 변형에서만 허용.",
+      "enum": [
+        "_SUID",
+        "_mSUID",
+        "block",
+        "collection",
+        "innerBlocks",
+        "keys",
+        "status",
+        "isAdded",
+        "isUpdated",
+        "isDeleted",
+        "isSelected",
+        "isActive",
+        "isLast",
+        "outerSector",
+        "outerBlock"
+      ]
+    },
+
+    "jsReservedWords": {
+      "$comment": "JS 예약어 + 자주 쓰이는 빌트인 / 글로벌. Sector 가 점 표기법 (`_c.카테고리[n].키`) 으로 접근되므로 충돌 시 sector.length / sector.toString 등 JS 빌트인이 우선되어 동작이 깨진다. naming.md §3-5 카탈로그 기준.",
+      "enum": [
+        "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do",
+        "else", "export", "extends", "finally", "for", "function", "if", "import", "in", "instanceof",
+        "new", "return", "super", "switch", "this", "throw", "try", "typeof", "var", "void", "while", "with", "yield",
+        "let", "static", "enum", "await", "async",
+        "null", "true", "false",
+        "constructor", "prototype", "length", "toString", "hasOwnProperty", "valueOf", "__proto__",
+        "Object", "Array", "String", "Number", "Boolean", "Date", "Math", "JSON", "Function", "Symbol", "RegExp"
+      ]
+    },
+
+    "ckey": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "description": "컬렉션키 (Sector 인스턴스 속성명). JS 식별자 규칙 + 시스템 게터 / JS 빌트인 충돌 차단. 컨벤션은 `f` 접두 + camelCase (`fName`, `fStatus`) — schema 강제 X. 운영 메타 호환을 위해 `_` 접두 변종은 별도 규칙으로 차단하지 않음 (단 시스템 게터 `_SUID`/`_mSUID` 는 차단).",
+      "not": {
+        "anyOf": [
+          { "$ref": "#/$defs/categoryReservedKeys" },
+          { "$ref": "#/$defs/sectorReservedKeys" },
+          { "$ref": "#/$defs/jsReservedWords" }
+        ]
+      }
+    },
+
+    "ckeyWithSuid": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "description": "Panel.Collection.Ckeys 전용 변형. `_SUID` 는 시스템 필수 등록 키이므로 허용. 그 외 시스템 게터 / JS 빌트인은 `ckey` 와 동일하게 차단.",
+      "not": {
+        "anyOf": [
+          { "$ref": "#/$defs/categoryReservedKeys" },
+          {
+            "enum": [
+              "_mSUID",
+              "block",
+              "collection",
+              "innerBlocks",
+              "keys",
+              "status",
+              "isAdded",
+              "isUpdated",
+              "isDeleted",
+              "isSelected",
+              "isActive",
+              "isLast",
+              "outerSector",
+              "outerBlock"
+            ]
+          },
+          { "$ref": "#/$defs/jsReservedWords" }
+        ]
+      }
+    },
+
+    "ckeysArray": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ckey" },
+      "description": "컨트롤 / 자식 ComboList / 자식 List / Tab / Calendar 등의 데이터 바인딩 키 배열. 시스템 게터 / JS 빌트인 충돌 시 런타임 동작 깨짐 — schema 레벨 차단."
+    },
+
+    "ckeysArrayWithSuid": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ckeyWithSuid" },
+      "description": "Panel.Collection.Ckeys 전용 — `_SUID` 시스템 키 허용."
+    },
+
+    "categoryName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "description": "Panel.Category 의 카테고리 이름. JS 식별자 규칙 + JS 빌트인 충돌 차단 (점 표기법 `_c.카테고리.*` 로 접근). 권장 컨벤션 = `Ctg` 접두 + PascalCase (예: `CtgItemList`) — 컨벤션 자체는 schema 강제 X (validator 경고). 안티패턴 (`CtgNew*`/`CtgEdit*`/`CtgAdd*`/`CtgInsert*`) 도 schema 강제 X — 별도 카테고리 정당화 케이스 (저장 전 변환/검증) 가 있으므로 validator 경고로만.",
+      "not": {
+        "anyOf": [
+          { "$ref": "#/$defs/categoryReservedKeys" },
+          { "$ref": "#/$defs/sectorReservedKeys" },
+          { "$ref": "#/$defs/jsReservedWords" }
+        ]
+      }
+    },
+
+    "categoryNameOrEmpty": {
+      "$comment": "ParamBlock.CategoryName 등 빈 문자열 (= 컬렉션 루트 / 기본 컨텍스트) 이 의미를 갖는 위치 전용. UserData 만 사용하는 ParamBlock 등에서 빈 문자열 허용.",
+      "type": "string",
+      "anyOf": [
+        { "const": "" },
+        { "$ref": "#/$defs/categoryName" }
+      ]
+    }
+  }
+}

package/contract-data/schema/v1/node.md

@@ -0,0 +1,32 @@
+# Node
+
+`Group | Control` 의 discriminated union. `Group.Contents[]` 의 자식으로 사용.
+
+## 식별
+
+| 노드 | 분기 필드 | 값 |
+|---|---|---|
+| Group | `ContentsType` | `"Group"` |
+| Control | `ControlType` | catalog.json `controlTypes[].value` 또는 v1 외 |
+
+Step은 Scenario 의 `Steps` 객체 직속이므로 이 union에 포함되지 않는다.
+
+## 트리 위치
+
+| 위치 | 자식 |
+|---|---|
+| `Step.Contents[]` | Group (Control 직접 자식 불가) |
+| `Step.FixedContentsTop[]` | Group |
+| `Step.FixedContentsBottom[]` | Group |
+| `Group.Contents[]` | Group \| Control (=`node.schema.json`) |
+| `Control(InputDate, Combo).Dialog.Layouts[0].Controls[]` | Control |
+
+## oneOf 동작
+
+- Group 분기: `ContentsType` 가 있으면 매치 → `group.schema.json` 검증
+- Control 분기: `ControlType` 가 있으면 매치 → `control.schema.json` 검증
+- 한 노드에 두 필드 동시 존재 시 oneOf 실패 (정확히 1개만 매치)
+
+## 검증 시 주의
+
+JSON Schema의 `discriminator` 키워드는 OpenAPI 확장이므로, 표준 호환 ajv 등에서는 `oneOf` + `required` + `const` 패턴만 사용한다.

package/contract-data/schema/v1/node.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/node.schema.json",
+  "title": "Node",
+  "description": "Group | Control 2-union (Step은 Scenario 직속이라 여기 포함하지 않음). Group.Contents[] 의 자식으로 사용.",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["ContentsType"],
+      "properties": {
+        "ContentsType": { "const": "Group" }
+      },
+      "$ref": "group.schema.json"
+    },
+    {
+      "type": "object",
+      "required": ["ControlType"],
+      "properties": {
+        "ControlType": { "type": "string" }
+      },
+      "$ref": "control.schema.json"
+    }
+  ]
+}

package/contract-data/schema/v1/patterns/_base.additional-meta.mjs

@@ -0,0 +1,135 @@
+// _base.additional-meta.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// L1 escape hatch — named-anchor override (README §7).
+//
+// 패턴 props 는 의도적으로 작다 (에이전트가 채우기 쉽도록). 그래서 패턴이
+// 노출하지 않는 엔진 메타데이터 (UseMove / MoveSteps, 데이터 연결 등) 를 넣을
+// 길이 없다. override 는 그 raw 메타데이터를 materialized 결과에 deep-merge 로
+// 주입하는 통로다.
+//
+// "위치 vs 메타데이터" 분리:
+//   · 메타데이터(무엇을 넣을지) 는 에이전트가 props.override 에 적는다 — 공통.
+//   · 위치(어느 노드에 넣을지) 는 각 materializer 가 anchor 이름으로 선언한다.
+//
+// 모든 패턴은 최소한 "root" anchor 를 지원 (결과 최상위 노드). molecule /
+// organism 은 자식 노드에 의미적 anchor 를 추가로 등록한다 (예: input-action 의
+// input / iconButton / badge). 순수 deep-merge 가 배열 자식(Contents[]) 을 통째
+// 교체해버리는 문제를 anchor 가 우회한다 — materializer 가 자식 노드를 만들 때
+// 그 자리에서 직접 merge 하므로.
+//
+// 사용 (materializer 측):
+//   import { makeOverride } from "../_base.additional-meta.mjs";
+//
+//   export default function materialize(props, ctx) {
+//     const ov = makeOverride(props.override, "input-action");
+//     const inputCtrl = ov.apply("input", buildInput(...));
+//     const iconBtn   = ov.apply("iconButton", buildIconButton(...));
+//     const root      = ov.apply("root", makeGroup({ children: [inputCtrl, ...] }));
+//     ov.finalize(["root", "input", "iconButton", "badge"]);
+//     return root;
+//   }
+//
+// 검증 정합: override 로 주입한 필드명이 어떤 엔진 스키마에든 정의돼 있으면
+// strict-fields (knownProps 전역 합집합) 를 통과한다. 어디에도 없는 신규/오타
+// 필드는 차단된다 — 의도된 안전장치.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// override deep-merge (design 키와 동일 의미론)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * patch 를 base 에 leaf-level deep-merge.
+ * - plain object ↔ plain object → 재귀 머지.
+ * - 그 외 (배열 / primitive / null) → patch 가 base 를 통째로 교체.
+ *   (배열 concat 안 함 — 명시적 교체가 예측 가능.)
+ * base 는 mutate 하지 않고 새 객체 반환.
+ */
+export function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function deepMerge(base, patch) {
+  if (!isPlainObject(patch)) return patch;
+  const out = isPlainObject(base) ? { ...base } : {};
+  for (const [k, v] of Object.entries(patch)) {
+    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// makeOverride — anchor 단위 override applicator
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 한 패턴 invocation 의 override 맵에 바인딩된 applicator 를 만든다.
+ *
+ * @param {object|undefined} override  props.override — { anchorName: patch, ... }.
+ *   undefined / null 이면 no-op applicator.
+ * @param {string} patternName  에러 메시지용 패턴 이름.
+ * @returns {{ apply(anchor, node): object, finalize(anchors?): void }}
+ *
+ * apply(anchor, node):
+ *   override 에 그 anchor 키가 있으면 deepMerge(node, patch) 반환 + 소비 기록,
+ *   없으면 node 그대로.
+ *
+ * finalize(anchors?):
+ *   소비되지 않은 override 키가 남아있으면 throw (오타 / 잘못된 위치 검출).
+ *   anchors 를 넘기면 "사용 가능한 anchor" 목록을 에러에 포함해 안내.
+ */
+export function makeOverride(override, patternName) {
+  if (override != null && !isPlainObject(override)) {
+    throw new Error(
+      `${patternName}.override: override 는 { anchorName: patch } 형태의 객체여야 함 ` +
+        `(받은 타입: ${Array.isArray(override) ? "array" : typeof override}).`,
+    );
+  }
+
+  const consumed = new Set();
+
+  function apply(anchor, node) {
+    if (override == null || !Object.hasOwn(override, anchor)) return node;
+    const patch = override[anchor];
+    if (!isPlainObject(patch)) {
+      throw new Error(
+        `${patternName}.override.${anchor}: patch 는 객체여야 함 ` +
+          `(받은 타입: ${Array.isArray(patch) ? "array" : typeof patch}).`,
+      );
+    }
+    consumed.add(anchor);
+    return deepMerge(node, patch);
+  }
+
+  function finalize(anchors) {
+    if (override == null) return;
+    const leftover = Object.keys(override).filter((k) => !consumed.has(k));
+    if (leftover.length === 0) return;
+
+    const valid = Array.isArray(anchors) ? new Set(anchors) : null;
+    // 유효 목록을 알면 "전혀 모르는 anchor" 와 "유효하지만 이 invocation 에서
+    // 생성 안 된 노드(예: badge prop 없이 badge override)" 를 구분해 안내한다.
+    const unknown = valid ? leftover.filter((k) => !valid.has(k)) : leftover;
+    const absent = valid ? leftover.filter((k) => valid.has(k)) : [];
+
+    const parts = [];
+    if (unknown.length) {
+      parts.push(
+        `알 수 없는 anchor ${unknown.map((k) => `'${k}'`).join(", ")}` +
+          (valid ? ` — 사용 가능한 anchor: ${[...valid].join(" / ")}` : ""),
+      );
+    }
+    if (absent.length) {
+      parts.push(
+        `anchor ${absent
+          .map((k) => `'${k}'`)
+          .join(", ")} 는 이 invocation 에서 생성되지 않은 노드 — 그 노드를 만드는 prop 이 있어야 override 가능`,
+      );
+    }
+    throw new Error(
+      `${patternName}.override: ${parts.join("; ")}. anchor 는 override 를 적용할 위치를 가리킨다 — 패턴 schema 의 override.propertyNames 참고.`,
+    );
+  }
+
+  return { apply, finalize };
+}