@wipco/sdui-editor 0.50.6 → 1.0.1

package/dist/index.d.ts

@@ -182,7 +182,15 @@ interface SpecStore {
     /** 이력 조회. `capabilities.history`가 false면 구현이 없다. */
     history?(id: string): Promise<PageRevision[]>;
 }
-/** 대소문자만 다른 id가 이미 있을 때 — 같은 대상을 가리켜 기존 페이지를 파괴한다 */
+/**
+ * 대소문자만 다른 id가 이미 있을 때 — 같은 대상을 가리켜 기존 페이지를 파괴한다.
+ *
+ * 판정은 상류의 몫이다: 편집기는 목록 스냅숏밖에 없어 경합 없이 알 수 없다.
+ * 번들 REST 어댑터는 저장 응답 409의 **본문이 id 충돌을 가리킬 때**(`existingId`),
+ * 또는 생성 전용 저장의 409일 때 이 예외로 올린다(rest-store.ts) — 409 자체는
+ * If-Match 낙관적 잠금 실패에도 쓰이는 코드라 상태 코드만으로는 가를 수 없다.
+ * 커스텀 SpecStore도 같은 상황이면 이 형으로 던져야 편집기가 문구를 고를 수 있다.
+ */
 declare class PageIdConflictError extends Error {
     readonly existingId: string;
     constructor(existingId: string);
@@ -239,8 +247,18 @@ declare class PageIdRejectedError extends Error {
  * 경로 탈출을 원천 차단한다. `{name}` 은 sdui-server 0.3.0 의 동적 상세 라우트
  * 문법이다 — 이 패턴이 몰라서 편집기 목록·편집 진입에서 패턴 스펙이 통째로
  * 사라졌던 적이 있다(실측: pages-index 에는 오는데 목록 필터가 걸러냄).
+ *
+ * 같은 규칙의 정규식 표현 — 공개 계약이라 남겨 둔다. **판정의 정본은
+ * {@link isValidPageId}가 위임하는 `@wipco/sdui`의 `isValidSpecId`다**(서버
+ * spec.rs 의 `valid_page_id`와 테스트로 짝을 맞춘 쪽). 규칙이 바뀌면 저쪽이
+ * 먼저 바뀌고 이 정규식은 따라간다.
  */
 declare const PAGE_ID_PATTERN: RegExp;
+/**
+ * id 문법 판정은 `isValidSpecId`에 위임한다 — 편집기가 정규식 사본으로 판정하면
+ * 서버와 어긋난 채 조용히 굴러간다(서버는 400, 편집기는 통과). 200자 상한만
+ * 편집기 쪽에서 덧댄다: 목록·URL이 다루는 길이를 묶는 편집기 자체 규칙이다.
+ */
 declare function isValidPageId(id: string): boolean;
 /**
  * 다이얼로그 조각 스펙의 id 접두.
@@ -254,6 +272,21 @@ declare function isValidPageId(id: string): boolean;
 declare const DIALOG_PREFIX = "dialogs/";
 /** 이 id가 다이얼로그 조각 관례를 따르는가 — {@link DIALOG_PREFIX} 접두 검사. */
 declare function isDialogSpecId(id: string): boolean;
+/**
+ * 화면 일부를 떼어 둔 조각 스펙의 id 접두 — `dialogs/`에 이은 두 번째 조각 이름공간.
+ *
+ * 0.48.0의 중첩 반복에서 생겼다: 바깥 `$index`를 안쪽으로 나르려면 그 자리가
+ * Fragment여야 해서(렌더러의 `$index`는 가장 안쪽 행을 읽는다) 다이얼로그가 아닌
+ * 조각이 필요해졌다. 소비 프로젝트(ERP)의 라우터는 둘 다 "주소창으로 열리면 안 되는
+ * 조각"으로 판정한다 — 편집기 목록도 같은 기준으로 갈라야 화면 탭에 조각이 섞이지 않는다.
+ */
+declare const FRAGMENT_PREFIX = "fragments/";
+/**
+ * 이 id가 조각(단독 화면이 아니라 Fragment가 끼워 쓰는 재료) 관례를 따르는가.
+ * 다이얼로그 조각({@link DIALOG_PREFIX})과 화면 조각({@link FRAGMENT_PREFIX}) 둘 다다.
+ * 다이얼로그 **전용** 동작(미리보기 열림 시딩 등)은 {@link isDialogSpecId}를 그대로 쓴다.
+ */
+declare function isFragmentSpecId(id: string): boolean;
 /** 스펙에서 표시용 제목 뽑기 — 모든 어댑터가 같은 규칙을 써야 목록이 갈리지 않는다 */
 declare function titleOf(spec: unknown): string | null;
 
@@ -279,15 +312,20 @@ declare function titleOf(spec: unknown): string | null;
  * {@link RestStoreConfig.headers}로 실어 주고(Bearer 등), 401은 그대로
  * {@link StoreUnauthorizedError}로 올려 소비 프로젝트의 로그인 흐름에 넘긴다.
  *
- * ## ERP 실계약
- * | 동작 | ERP 경로 | 비고 |
+ * ## 기본 계약 = ERP 실계약
+ * | 동작 | 기본 경로 | 비고 |
  * | --- | --- | --- |
  * | 목록 | `GET /ui/pages-index` | 제목·수정자·수정시각·etag. 권한 `setting.update` 필요 |
  * | 목록(대체) | `GET /ui/manifest` | `{count, specs:{id:etag}}` — **제목이 없다** |
  * | 읽기 | `GET /ui/pages/{id}` | 스펙 JSON + `ETag`, `If-None-Match` → 304 |
- * | 쓰기 | `PUT /ui/pages/{id}` | `{spec, title?}`, 권한 `setting.update` |
+ * | 쓰기 | `PUT /ui/pages/{id}` | `{spec, title?}`, `If-Match` 어긋나면 409, 권한 `setting.update` |
  * | 삭제 | — | **없다.** `DELETE`는 405다 |
  *
+ * 경로·안내 문구는 {@link RestStoreConfig}로 갈아끼울 수 있다. 기본값이 ERP 값인
+ * 이유는 하나다 — 지금 이 어댑터를 쓰는 실소비자가 ERP뿐이고, 기본값을 중립으로
+ * 바꾸면 그 소비자의 화면 문구가 소리 없이 바뀐다. ERP가 아닌 프로젝트는 자기
+ * 경로와 문구를 주입하면 남의 프로젝트 이름이 화면에 나가지 않는다.
+ *
  * ## 목록의 제목 간극
  * `/ui/manifest`에는 제목이 없지만 ERP에는 편집기 전용 목록 `GET /ui/pages-index`가
  * 이미 있다(id·title·etag·updatedAt·updatedBy). 매니페스트는 모든 클라이언트가 진입할 때
@@ -303,10 +341,21 @@ declare function titleOf(spec: unknown): string | null;
  * - **`_` 접두 id(`_nav`)**: `GET/PUT /ui/pages/_nav`는 404다(내비는 `/ui/nav-spec`이
  *   따로 있다). 여기서는 왕복 전에 막고 이유를 밝힌다 — 그냥 흘려보내면 사용자는
  *   "페이지 없음"만 보고 왜인지 알 수 없다.
- * - **원자적 낙관적 잠금**: ERP의 PUT은 `If-Match`를 읽지 않는다(엉뚱한 ETag를 보내도
- *   200). 그래서 여기서 읽기→비교→쓰기로 흉내 내지만 그 사이에 틈이 있다.
+ * - **원자적 낙관적 잠금**: 저장에는 `If-Match`를 실어 보낸다 — sdui-server처럼 이
+ *   헤더를 검사하는 상류에서는 선검사 뒤의 경합까지 409로 막힌다. 다만 `If-Match`를
+ *   읽지 않는 구버전 서버(엉뚱한 ETag를 보내도 200)에 붙을 수 있고, 200 응답만으로는
+ *   서버가 검사했는지 알 수 없다. 그래서 읽기→비교 선검사를 함께 유지하고
  *   `capabilities.atomicLocking = false`로 알린다.
  */
+/** 스펙 저장소 경로 — 소비 프로젝트의 라우트가 `/ui/*`가 아닐 때 갈아끼운다. */
+interface RestStorePaths {
+    /** 편집기용 목록. 기본 `/ui/pages-index` — 404면 {@link manifest}로 물러난다. */
+    index?: string;
+    /** 목록 폴백(제목 없음). 기본 `/ui/manifest`. */
+    manifest?: string;
+    /** 단건 읽기(GET)·쓰기(PUT). 기본 `` (id) => `/ui/pages/${id}` ``. */
+    page?: (id: string) => string;
+}
 interface RestStoreConfig {
     /**
      * 소비 프로젝트 백엔드의 베이스 URL. 기본값은 빈 문자열 = **같은 오리진**이다 —
@@ -326,12 +375,35 @@ interface RestStoreConfig {
     timeoutMs?: number;
     /** 401을 받았을 때 — 소비 프로젝트가 자기 로그인 흐름을 태울 자리 */
     onUnauthorized?: () => void;
+    /** 저장소 HTTP 경로. 기본값은 sdui-server(ERP)의 `/ui/*` 배치다. */
+    paths?: RestStorePaths;
+    /**
+     * 목록 위 배너에 나가는 제약 문구. 기본값은 ERP 서버 형편을 설명한다 —
+     * ERP가 아닌 소비 프로젝트는 자기 서버의 제약(또는 빈 배열)으로 바꿔 단다.
+     */
+    limitations?: string[];
+    /**
+     * 403인데 응답 본문에 메시지가 없을 때의 폴백 문구. 본문에 `message`/`error`가
+     * 있으면 **서버가 준 그 문장이 우선**이다 — 권한 체계는 소비 프로젝트마다 달라서
+     * 편집기가 권한 이름을 지어내면 남의 프로젝트에서 거짓 안내가 된다.
+     */
+    forbiddenHint?: string;
+    /**
+     * `_` 접두 id를 거부할 때의 안내 문구. 접두 규칙 자체는 sdui-server의
+     * `servable_page_id` 계약(내부 데이터는 페이지 경로로 안 나온다)이라 끄지 않는다.
+     */
+    internalIdHint?: string;
 }
 declare class RestSpecStore implements SpecStore {
     readonly capabilities: StoreCapabilities;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly config;
+    private readonly indexPath;
+    private readonly manifestPath;
+    private readonly pagePath;
+    private readonly forbiddenHint;
+    private readonly internalIdHint;
     constructor(config?: RestStoreConfig);
     private request;
     /** 상류 오류를 사람이 읽을 수 있는 문장으로 — 상류가 준 메시지가 있으면 그대로 싣는다 */
@@ -376,7 +448,7 @@ interface SduiEditorProps {
     /**
      * 스펙을 그릴 때 쓸 컴포넌트 어휘. **소비 프로젝트가 자기 것을 넣는 자리다.**
      *
-     * 생략하면 라이브러리가 아는 66종(기본 39 + DS 6 + 표시 위젯 21)으로 그린다.
+     * 생략하면 라이브러리가 아는 84종(기본 42 + DS 6 + 표시 위젯 36)으로 그린다.
      * 위젯은 지연 로드라 안 쓰면 내려오지 않는다(`editorRegistry` 주석 참고).
      *
      * 소비 프로젝트가 `createRegistry`로 어휘를 넓혔다면 **그 레지스트리를 그대로 넘긴다.**
@@ -391,7 +463,7 @@ interface SduiEditorProps {
      */
     registry?: SduiRegistry;
     /**
-     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 69종.
+     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 89종.
      *
      * `registry`를 넓혔다면 여기도 같이 넓혀야 한다 — 레지스트리는 "그릴 수 있는 이름",
      * 이쪽은 "빌더가 프롭을 그릴 줄 아는 이름"이라 둘은 따로 논다.
@@ -400,7 +472,8 @@ interface SduiEditorProps {
     catalog?: Record<string, SduiComponentMeta>;
     /**
      * 뷰어에서 스펙의 `navigate` 액션이 나왔을 때. 주지 않으면 뷰어 안에서 그 페이지를
-     * 열어 본다(절대 URL은 무시한다 — 편집기를 마운트한 화면을 날려 버리지 않기 위해).
+     * 열어 본다 — 쿼리·해시는 페이지 id가 아니라 떼어 내고, 절대 URL은 무시한다
+     * (편집기를 마운트한 화면을 날려 버리지 않기 위해).
      */
     onNavigate?: (to: string) => void;
     /**
@@ -458,6 +531,19 @@ interface SduiEditorProps {
  */
 declare function SduiEditor({ store, view, onViewChange, defaultView, chrome, registry, catalog, onNavigate, viewerAdapter, can, previewFetch, previewEntitySearch, className, }: SduiEditorProps): React.JSX.Element;
 
+/**
+ * 주소 → 편집기 화면. `base`는 편집기가 마운트된 경로다(예: `/_editor`).
+ *
+ * pathname이 base 밖이거나 알 수 없는 꼴이면 목록으로 떨어진다 — 제어 모드에서
+ * "이상한 주소"의 답은 오류 화면이 아니라 안전한 시작점이다.
+ */
+declare function viewFromPath(base: string, pathname: string): SduiEditorView;
+/**
+ * 편집기 화면 → 주소. {@link viewFromPath}의 역함수여야 뒤로 가기가 성립한다 —
+ * 그래서 인코딩도 같은 결로 세그먼트별이다(구분자 `/`는 살리고 세그먼트 안만 인코딩).
+ */
+declare function pathFromView(base: string, view: SduiEditorView): string;
+
 interface PageListViewProps {
     store: SpecStore;
     onEdit: (id: string) => void;
@@ -473,14 +559,14 @@ interface EditorViewProps {
     /**
      * 이 화면(빌더 캔버스·JSON 미리보기)이 스펙을 그릴 때 쓸 레지스트리.
      *
-     * 생략하면 {@link editorRegistry} — 라이브러리가 아는 어휘 66종이다. 소비 앱이
+     * 생략하면 {@link editorRegistry} — 라이브러리가 아는 어휘 84종이다. 소비 앱이
      * `createRegistry`로 자기 컴포넌트를 얹었다면 **그것을 그대로 넘겨야** 편집 화면과
      * 운영 화면이 같은 그림이 된다. 두 렌더러(빌더·미리보기)에 같은 값이 간다 —
      * 한쪽만 넓으면 모드를 바꿀 때 화면이 달라진다.
      */
     registry?: SduiRegistry;
     /**
-     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 69종
+     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 89종
      * (`@wipco/sdui/meta`의 `allComponentMeta`).
      *
      * `registry`에 앱 고유 컴포넌트를 얹었다면 그 메타데이터도 여기 합쳐 넘겨야
@@ -520,8 +606,8 @@ interface ViewerViewProps {
      * 렌더링 어휘. **캔버스와 같은 값을 받아야 한다** — 편집 중에는 그려지던 위젯이
      * "보기"로 넘어가면 사라지는 것이 사용자에게는 저장이 깨진 것으로 보인다.
      *
-     * 생략하면 {@link editorRegistry} 66종 — 캔버스의 기본값과 같은 값이다.
-     * 예전에는 여기가 비면 `SduiRenderer`의 기본값(`defaultRegistry` 39종)으로 떨어졌다.
+     * 생략하면 {@link editorRegistry} 84종 — 캔버스의 기본값과 같은 값이다.
+     * 예전에는 여기가 비면 `SduiRenderer`의 기본값(`defaultRegistry`)으로 떨어졌다.
      * `SduiEditor` 셸이 `registry ?? editorRegistry`로 때워 두었지만 `ViewerView`는
      * 개별 export라, **자기 셸을 짜서 단독 마운트한 소비자에게는 그 때움이 안 닿았다.**
      * 때우는 자리를 셸에서 프롭 기본값으로 내린 이유가 그것이다.
@@ -599,7 +685,24 @@ declare const TEMPLATES: PageTemplate[];
 type GradedIssue = SpecIssue & {
     severity: 'error' | 'warning';
 };
-declare function gradeIssues(spec: unknown): GradedIssue[];
+interface GradeIssuesOptions {
+    /**
+     * 대조할 컴포넌트 어휘. 생략하면 기본 레지스트리(defaultRegistry) — 편집 화면은
+     * 자기가 실제로 그리는 레지스트리의 키 집합을 넘겨야 "그려지는데 경고가 뜨는"
+     * 어긋남이 없다.
+     */
+    known?: Set<string>;
+    /**
+     * 컴포넌트 → 아는 슬롯 이름들(모르면 null = 검사 안 함). 검증기의 슬롯 이름 검사는
+     * 이 표가 있어야만 돈다 — 실측 사고(`Show`에 `slots.fallback`을 달아 UI가 조용히
+     * 사라졌는데 검증 통과)가 이 검사의 존재 이유다. `@wipco/sdui/meta`의
+     * `metaSlotNames`가 곧바로 쓸 수 있는 구현이다.
+     * (validate.ts의 `SlotNamesOf`와 같은 형 — 그 타입이 패키지 루트로 아직 안 나와
+     *  구조적으로 적는다.)
+     */
+    slotNamesOf?: (component: string) => Set<string> | null;
+}
+declare function gradeIssues(spec: unknown, options?: GradeIssuesOptions): GradedIssue[];
 
 /**
  * 미리보기 시딩 — **순수 모듈**(DOM·React 없음, node:test로 그대로 검증된다).
@@ -847,6 +950,12 @@ interface DropTarget {
     /** 삽입 위치. 슬롯 길이를 넘으면 끝에 붙는다(음수는 0). */
     readonly index: number;
 }
+/**
+ * 같은 자리를 가리키는가 — 삽입 지점·드롭 힌트는 값이라 참조 비교로는 헛된 갱신이 난다.
+ * 비교가 여기(타입이 사는 곳) 한 벌인 이유: 트리와 리듀서가 각자 사본을 들면
+ * 한쪽만 고쳐질 때 두 화면의 "같은 자리" 판정이 어긋난다.
+ */
+declare function sameDropTarget(a: DropTarget | null, b: DropTarget | null): boolean;
 interface BuilderText {
     readonly kind: 'text';
     readonly id: NodeId;
@@ -1018,7 +1127,7 @@ interface DropDomContext {
  * ## 화이트리스트를 쓰지 않는 이유 (실측)
  *
  * 스펙 84개에 나타난 부모→자식 조합은 **232종**(슬롯까지 구분하면 242종)이고, 그중
- * 컴포넌트 이름이 이 라이브러리 어휘 69종 밖인 것도 스물 몇 가지다(소비 앱이 레지스트리에
+ * 컴포넌트 이름이 이 라이브러리 어휘(잰 시점 69종) 밖인 것도 스물 몇 가지다(소비 앱이 레지스트리에
  * 얹은 `ExcelUploadCard`·`ApprovalStepper` 같은 것들). 손으로 유지되는 허용 목록은
  * 하루면 낡는다. 그래서 **막는 규칙은 최소로, 나머지는 추천으로** 나눴다.
  *
@@ -1081,7 +1190,7 @@ declare function recommendedChildren(parent: string | null, slot?: string, limit
  *   psql -tA -d wipco_erp_dev_specs -c "select json_agg(spec) from ui_specs where id not like '\\_%'"
  *
  * 키는 `부모>자식` 또는 `부모#슬롯>자식`, 최상위는 `$body>자식`, 문자열 자식은 `#text`다.
- * 어휘 69종 밖의 이름(ExcelUploadCard·ApprovalStepper·Disclosure…)이 섞여 있는데
+ * 어휘(잰 시점 69종) 밖의 이름(ExcelUploadCard·ApprovalStepper·Disclosure…)이 섞여 있는데
  * 일부러 남겨 뒀다 — 소비 앱이 레지스트리에 얹은 컴포넌트도 편집 대상이고,
  * 이 표는 **금지 목록이 아니라 추천 근거**라서 모르는 이름이 있어도 해롭지 않다.
  *
@@ -1151,7 +1260,7 @@ declare const EMPTY_SELECTION: Selection;
 declare function isSelected(selection: Selection, id: NodeId): boolean;
 /** 다중 선택인가 — 정렬 도구·일괄 삭제 버튼을 켜는 조건. */
 declare function isMultiSelection(selection: Selection): boolean;
-/** 같은 자리를 가리키는가. 삽입 지점은 값이라 참조 비교로는 헛된 리렌더가 난다. */
+/** 같은 자리를 가리키는가 — 구현은 {@link sameDropTarget} 하나다(이 이름은 공개 표면 호환용). */
 declare function sameInsertionPoint(a: DropTarget | null, b: DropTarget | null): boolean;
 /**
  * 한 덩어리로 묶을 시간 창(ms).
@@ -1350,7 +1459,7 @@ interface BuilderViewProps {
     readonly canvasInitialState?: Record<string, SduiPropValue>;
     /**
      * 캔버스가 그릴 때 쓸 레지스트리. 생략하면 {@link editorRegistry}(라이브러리 어휘
-     * 66종 + 렌더러 내장 `ForEach`)다. 소비 앱이 자기 컴포넌트를 얹었다면 **그 레지스트리를
+     * 84종 + 렌더러 내장 `ForEach`·`Fragment`)다. 소비 앱이 자기 컴포넌트를 얹었다면 **그 레지스트리를
      * 그대로 넘겨야** 캔버스에 앱과 같은 그림이 나온다 — 안 넘기면 앱 고유 이름
      * (`ExcelUploadCard` 등)이 "등록되지 않은 컴포넌트" 자리 표시가 된다(선택·이동은 된다).
      */
@@ -1389,19 +1498,20 @@ declare function BuilderView({ spec, syncKey, onSpecChange, onOpenJson, onSave,
  *
  * ## 왜 `defaultRegistry`로는 모자라나
  *
- * 팔레트는 메타데이터(`@wipco/sdui/meta`)가 아는 어휘 **69종**을 내건다(`hidden`인
- * `Toast`만 빠져 화면에는 68종). 그런데
- * `defaultRegistry`는 39종(+ 렌더러 내장 `ForEach`)뿐이라, 드롭인 사용자는 팔레트에서
- * 집을 수 있는 것의 42%를 집어 **아무것도 그려지지 않는 페이지**를 만들 수 있었다.
- * 팔레트에 있는데 안 그려지는 것은 빌더의 전제를 깨는 종류의 어긋남이라 기본을 넓힌다.
+ * 팔레트는 메타데이터(`@wipco/sdui/meta`)가 아는 어휘 **89종**을 내건다(`hidden`인
+ * `Toast`만 빠져 화면에는 88종). 그런데
+ * `defaultRegistry`는 42종(+ 렌더러 내장 `ForEach`·`Fragment`)뿐이라, 드롭인 사용자는
+ * 팔레트에서 집을 수 있는 것의 절반 가까이를 집어 **아무것도 그려지지 않는 페이지**를
+ * 만들 수 있었다. 팔레트에 있는데 안 그려지는 것은 빌더의 전제를 깨는 종류의
+ * 어긋남이라 기본을 넓힌다.
  *
- * 39 + DS 6 + 표시 위젯 21 = **66종**이고, `defaultRegistry`를 통째로 품는다
- * (`test/registry-default.test.ts`가 포함 관계를 실제로 센다).
+ * 42 + DS 6 + 표시 위젯 36 = **84종**이고, `defaultRegistry`를 통째로 품는다
+ * (`test/registry-default.test.ts`가 포함 관계와 개수를 실제로 센다).
  *
  * ## 넓히되 코드 분할은 깨지 않는다
  *
- * 위젯 21종을 `defaultRegistry`처럼 정적으로 물면 그 21종이 편집기를 쓰는 모든 소비자의
- * 초기 청크에 붙는다(측정치 77.4kB — 아래 청크 합). 0.3.0에서 위젯별 진입점을 만든 이유가
+ * 위젯 36종을 `defaultRegistry`처럼 정적으로 물면 전부가 편집기를 쓰는 모든 소비자의
+ * 초기 청크에 붙는다(21종이던 때 측정치 77.4kB — 아래 청크 합). 0.3.0에서 위젯별 진입점을 만든 이유가
  * 정확히 그것을 막기 위해서였고, 묶음(`@wipco/sdui/widgets`)을 한 번이라도 정적으로 물면
  * 개별 진입점의 `lazy`까지 도로 합쳐진다(widgets/index.ts 주석 참고).
  *
@@ -1426,11 +1536,13 @@ declare function BuilderView({ spec, syncKey, onSpecChange, onOpenJson, onSave,
  *  아니라 **청크 목록에 위젯 이름이 그대로 남아 있는가**다 — 하나라도 초기 청크로
  *  합쳐졌다면 정적 경로가 어디선가 생긴 것이다.)
  *
- * ## 여기 없는 것 — `Chart`·`MapPreview`
+ * ## 여기 없는 것 — `Chart`·`MapPreview`·`ExcelUploadCard`
  *
- * 메타데이터 69종에서 이 둘과 `ForEach`를 빼면 66이다. **69가 아닌 이유가 그 셋이고,
- * 셋 다 이유가 다르다.** `ForEach`는 렌더러 내장이라 레지스트리를 애초에 안 거친다.
- * 나머지 둘은 이렇다.
+ * 메타데이터 89종에서 이 셋과 `ForEach`·`Fragment`를 빼면 84다. **89가 아닌 이유가
+ * 그 다섯이고, 이유는 두 갈래다.** `ForEach`·`Fragment`는 렌더러 내장이라 레지스트리를
+ * 애초에 안 거친다(Fragment는 어댑터 훅으로 다른 스펙을 가져와야 해서 레지스트리
+ * 컴포넌트로는 성립하지 않는다). `ExcelUploadCard`는 xlsx가 optional peer라 아래
+ * 둘과 같은 이유로 뺐다(0.31.0에서 rich로 들어왔다). 나머지 둘은 이렇다.
  *
  * 그 둘은 `@wipco/sdui/rich`에 있고 recharts·ol이 **optional peerDependency**다
  * (`packages/sdui/package.json`의 `peerDependenciesMeta`). 기본값이 그 진입점을 물면
@@ -1443,8 +1555,8 @@ declare function BuilderView({ spec, syncKey, onSpecChange, onOpenJson, onSave,
  * `packages/sdui/node_modules`에서 둘을 찾아낸다. 진짜 소비자에게는 그 경로가 없다.
  *
  * 두 이름은 소비자가 `registry` 프롭으로 얹고(`richComponents`가 그 스위치다),
- * 얹지 않으면 팔레트가 "등록되지 않음"으로 표시한다. **이 2종이 팔레트와 캔버스 사이에
- * 남는 유일한 격차이고, 그건 메우는 게 아니라 의도한 것이다.**
+ * 얹지 않으면 팔레트가 "등록되지 않음"으로 표시한다. **ExcelUploadCard까지 이 3종이
+ * 팔레트와 캔버스 사이에 남는 유일한 격차이고, 그건 메우는 게 아니라 의도한 것이다.**
  *
  * ## `AutocompleteField`는 넣는다
  *
@@ -1456,10 +1568,10 @@ declare function BuilderView({ spec, syncKey, onSpecChange, onOpenJson, onSave,
  */
 
 /**
- * 편집 화면(캔버스·미리보기·뷰어)의 기본 어휘 66종.
+ * 편집 화면(캔버스·미리보기·뷰어)의 기본 어휘 84종.
  *
  * 기본값을 정하는 자리는 이 값 **하나**다. 파일 머리말의 순환 문제 때문에 값이
- * `BuilderView.tsx`에 갇혀 있던 동안 `Canvas`와 `ViewerView`가 각자 39종으로 떨어졌고,
+ * `BuilderView.tsx`에 갇혀 있던 동안 `Canvas`와 `ViewerView`가 각자 기본 39종(당시)으로 떨어졌고,
  * 그 어긋남을 화면에서 설명하는 것이 아무 데도 없었다. 새 기본값이 필요하면
  * 여기서만 바꾸고, 새 화면을 만들면 여기서 가져다 쓴다.
  */
@@ -1476,15 +1588,16 @@ interface CanvasProps {
     /**
      * 소비 앱이 자기 컴포넌트를 얹은 레지스트리.
      *
-     * 생략하면 {@link editorRegistry} — 라이브러리 어휘 **66종**(렌더러 기본 39 + DS 6 +
-     * 표시 위젯 21, 여기에 렌더러 내장 `ForEach`)이다. 팔레트가 내거는 68종 중 여기 없는
-     * 것은 `Chart`·`MapPreview` 둘뿐이고, 그건 recharts·ol이 **optional peerDependency**라
-     * 일부러 뺀 것이다(editor-registry.tsx 주석). 소비자가 그 둘을 쓰려면 직접 얹어야 한다.
+     * 생략하면 {@link editorRegistry} — 라이브러리 어휘 **84종**(렌더러 기본 42 + DS 6 +
+     * 표시 위젯 36, 여기에 렌더러 내장 `ForEach`·`Fragment`)이다. 팔레트가 내거는 88종 중
+     * 여기 없는 것은 `Chart`·`MapPreview`·`ExcelUploadCard` 셋뿐이고, 그건 recharts·ol·xlsx가
+     * **optional peerDependency**라 일부러 뺀 것이다(editor-registry.tsx 주석).
+     * 소비자가 그 셋을 쓰려면 직접 얹어야 한다.
      *
-     * 어휘 밖 컴포넌트(ExcelUploadCard 등)를 쓰는 스펙을 편집하려면 반드시 넘겨야 한다 —
+     * 어휘 밖 컴포넌트를 쓰는 스펙을 편집하려면 반드시 넘겨야 한다 —
      * 안 넘기면 그 노드는 "등록되지 않은 컴포넌트" 자리 표시로 그려진다(선택·이동은 된다).
      * 넓힐 때는 `createRegistry({ ...editorRegistry, ...myComponents })`로 **얹어야** 한다.
-     * `createRegistry(myComponents)`는 바탕이 `defaultRegistry` 39종이라 위젯 27종이 빠진다.
+     * `createRegistry(myComponents)`는 바탕이 `defaultRegistry` 42종이라 위젯 42종이 빠진다.
      */
     registry?: SduiRegistry;
     /** `Can`의 판정. 캔버스는 게이트를 열어 두므로 보통 넘길 일이 없다. */
@@ -1516,8 +1629,8 @@ interface CanvasProps {
 declare function Canvas({ doc, catalog, selection, hover, dispatch, 
 /**
  * 기본값이 여기 붙어 있는 이유 — 이 자리가 비면 한 단계 아래
- * `createEditRegistry(base = defaultRegistry)`가 받아 **39종**으로 떨어진다.
- * `BuilderView`로 열면 셸이 66종을 내려 주지만, 자기 셸을 짜서 `Canvas`를 단독으로
+ * `createEditRegistry(base = defaultRegistry)`가 받아 **42종**으로 떨어진다.
+ * `BuilderView`로 열면 셸이 84종을 내려 주지만, 자기 셸을 짜서 `Canvas`를 단독으로
  * 마운트한 소비자에게는 그 셸이 없다. 그러면 팔레트가 `Timeline`을 멀쩡히 내걸고
  * 캔버스는 "등록되지 않은 컴포넌트: Timeline"이라 답하는데, 왜 다른지 설명하는 것이
  * 화면 어디에도 없다 — 소비자는 "라이브러리에 없구나"로 오귀인한다.
@@ -1529,7 +1642,7 @@ interface PaletteProps {
     selection: Selection;
     dispatch: (action: EditorAction) => void;
     /**
-     * 팔레트에 띄울 메타데이터. 생략하면 라이브러리 어휘 69종(`allComponentMeta`).
+     * 팔레트에 띄울 메타데이터. 생략하면 라이브러리 어휘 89종(`allComponentMeta`).
      * 소비 앱이 얹은 컴포넌트도 팔레트에 내려면 그 메타데이터를 합쳐 넘긴다.
      */
     catalog?: Record<string, SduiComponentMeta>;
@@ -1916,11 +2029,20 @@ interface Candidate {
 /**
  * 액션이 들어가는 프롭인가.
  *
- * 렌더러는 `on`으로 시작하는 프롭만 핸들러로 바꾸지만, `SearchResults.rowClick`처럼
- * **컴포넌트가 자기 손으로 dispatch하는 프롭**이 실측에 있다(메타데이터는 `kind: 'action'`).
- * 둘 다 액션 자리로 본다. 메타데이터를 모르는 컴포넌트는 이름 규칙만으로 판단한다.
+ * 판정 근거는 셋이고 이 순서로 세다.
+ *
+ * 1. **메타데이터가 아는 프롭은 메타가 정답이다.** `SearchResults.rowClick`처럼
+ *    `on*`이 아니어도 컴포넌트가 자기 손으로 dispatch하는 프롭은 `kind: 'action'`으로
+ *    선언돼 있고, 반대로 `Tabs.onChrome`처럼 `on`으로 시작하지만 액션이 아닌 프롭도 있다.
+ * 2. **메타가 모르는 프롭은 렌더러의 규칙을 따른다** — `on` 접두 + 값 모양
+ *    (`SduiRenderer`는 둘 다 봐야 핸들러로 바꾼다). 값이 안 실려 온 호출(문서 순회 등)과
+ *    **빈 배열**은 이름만으로 낙관한다 — 빈 목록은 "액션이 아니다"의 증거가 못 되고,
+ *    여기서 강등되면 액션을 다 지운 `on*` 프롭이 액션 편집기 대신 일반 편집기로 열린다.
+ * 3. 이름 규칙 밖이라도 **값이 액션 모양이면** 액션 편집기가 맞다. 값 모양만으로 판정하지
+ *    않는 것은 1 때문이다 — 실측에 `Form.initial = {"action":"reject",…}` 같은 폼 초기값이
+ *    있어서, 메타를 무시하고 모양만 보면 액션으로 오인한다.
  */
-declare function looksLikeActionProp(component: string, prop: string, catalog?: SduiCatalog): boolean;
+declare function looksLikeActionProp(component: string, prop: string, catalog?: SduiCatalog, value?: SduiPropValue): boolean;
 
 /**
  * `$item`/`$index`가 **의미를 갖는 자리인지** 판정한다.
@@ -1984,8 +2106,14 @@ interface BindingContext extends BindingSource {
     readonly scope: ForEachScope;
 }
 declare function bindingContextFor(source: BindingSource, nodeId: NodeId | null): BindingContext;
-/** 한 번에 만들고 싶을 때(테스트·간단한 호출부). 위 두 단계를 그냥 붙인 것이다. */
-declare function createBindingContext(doc: BuilderDoc, nodeId: NodeId | null, pageIds?: readonly string[]): BindingContext;
+/**
+ * 한 번에 만들고 싶을 때(테스트·간단한 호출부). 위 두 단계를 그냥 붙인 것이다.
+ *
+ * `catalog`를 끝까지 내려보내야 소비 앱이 카탈로그로 선언한 액션 프롭
+ * (`kind: 'action'`, 이름이 `on*`이 아닌 것)이 후보 수집(`forEachAction`)에 잡힌다 —
+ * 안 넘기면 그 프롭 안의 open/close 키·경로·엔드포인트가 자동완성에서 빠진다.
+ */
+declare function createBindingContext(doc: BuilderDoc, nodeId: NodeId | null, pageIds?: readonly string[], catalog?: SduiCatalog): BindingContext;
 
 /**
  * 값 하나를 편집한다 — **상수인가 바인딩인가**를 고르고, 바인딩이면 종류까지.
@@ -2017,9 +2145,15 @@ interface BindingEditorProps {
     depth?: number;
     /** 바인딩을 받을 수 없는 자리(예: `$state`의 default)에서 종류 선택을 감춘다. */
     literalOnly?: boolean;
+    /**
+     * 액션의 값 자리인가 — `{"$event"}` 참조가 사는 유일한 컨텍스트라, 켜야 종류
+     * 선택지에 "이벤트"가 나온다(액션 밖에서 고르면 렌더 시점에 null이 된다).
+     * 값이 이미 `$event`면 플래그와 무관하게 표시한다 — 감추면 고칠 창구가 사라진다.
+     */
+    eventScope?: boolean;
     'aria-label'?: string;
 }
-declare function BindingEditor({ value, onChange, ctx, meta, autoFocus, depth, literalOnly, 'aria-label': ariaLabel, }: BindingEditorProps): React__default.JSX.Element;
+declare function BindingEditor({ value, onChange, ctx, meta, autoFocus, depth, literalOnly, eventScope, 'aria-label': ariaLabel, }: BindingEditorProps): React__default.JSX.Element;
 
 /**
  * `on*` 프롭에 붙는 **액션 목록**을 편집한다.
@@ -2071,13 +2205,34 @@ interface ActionList {
      * 그래서 개수가 하나로 남는 한 원래 모양을 지킨다.
      */
     readonly single: boolean;
-    /** 액션이 아닌 것이 섞여 있었는가 — 그대로 보존하되 화면에 알린다. */
+    /**
+     * 액션 객체가 아닌 항목 — 그대로 보존하되 화면에 알린다.
+     *
+     * `{"$arg":"이름"}`(조각이 전달받은 액션)도 여기로 온다. 렌더러에게는 액션 자리의
+     * 1급 항목이지만, 편집기가 폼으로 그릴 본문이 없어 목록에는 내지 않는다 —
+     * 대신 **원래 자리**({@link ActionList.strayAt})를 지켜 되쓴다.
+     */
     readonly strays: readonly SduiPropValue[];
+    /**
+     * 각 stray **앞에 놓인 실제 액션의 수**(strays와 같은 순서).
+     *
+     * 렌더러는 `[{...고정}, {"$arg":"onSuccess"}]` 같은 혼합 목록을 **그 자리 순서대로**
+     * 펼쳐 실행한다(`expandActionEntries`). 편집기가 stray를 꼬리로 몰아 되쓰면
+     * 필드 하나 고친 저장에 실행 순서가 조용히 바뀐다 — 그 사고를 막는 좌석표다.
+     *
+     * 절대 인덱스가 아니라 "앞선 액션 수"인 이유: 편집기가 만지는 것은 액션뿐이라,
+     * 절대 인덱스는 앞 액션 하나만 지워도 어긋난다. 액션 기준 앵커는 이웃 맞바꿈·삽입을
+     * 그대로 견디고, 삭제만 {@link removeActionAt}이 앵커를 같이 당겨 주면 된다.
+     */
+    readonly strayAt: readonly number[];
 }
 declare function readActionList(value: SduiPropValue | undefined): ActionList;
 /**
  * 다시 스펙 값으로. 액션이 하나도 없으면 `undefined`를 돌려주고,
  * 호출부는 그걸로 프롭 자체를 지운다(`setProp(doc, id, name, undefined)`).
+ *
+ * stray는 {@link ActionList.strayAt}의 앵커대로 — 자기 앞에 그 수만큼 액션을 두고 —
+ * 끼워 넣는다. 앵커가 남은 액션 수보다 크면 꼬리로 간다(상한일 뿐, "항상 꼬리로 몰림"은 없다).
  */
 declare function writeActionList(list: ActionList): SduiPropValue | undefined;
 
@@ -2104,4 +2259,4 @@ declare function formatAction(action: ActionValue): string;
 /** 액션 목록 전체를 한 줄로 — 프롭 목록에서 "무엇이 붙어 있나"를 볼 때. */
 declare function formatActionList(actions: readonly ActionValue[]): string;
 
-export { ActionEditor, type ActionEditorProps, type ActionList, type ActionValue, type BindingContext, BindingEditor, type BindingEditorProps, type BindingSource, type BuilderChild, type BuilderDoc, type BuilderFidelity, type BuilderNode, type BuilderPageMeta, type BuilderText, BuilderView, type BuilderViewProps, COALESCE_WINDOW_MS, Canvas, type CanvasProps, type ChildLabel, DEFAULT_SLOT, DIALOG_PREFIX, type DropDomContext, type DropTarget, type DropVerdict, EMPTY_SELECTION, type EditorAction, type EditorState, EditorView, type EditorViewProps, type FlattenOptions, type GradedIssue, HISTORY_LIMIT, HistoryBar, type HistoryBarProps, type HistoryEntry, INITIAL_PREVIEW_SETUP, Inspector, type InspectorChange, type InspectorProps, type ManualSeed, type NodeId, PAGE_ID_PATTERN, PageExistsError, PageGoneError, PageIdConflictError, PageIdRejectedError, PageListView, type PageListViewProps, type PageMeta, type PageRecord, type PageRevision, type PageTemplate, Palette, type PaletteProps, type PreviewAdapterOptions, type PreviewEntityOption, type PreviewEntitySearch, type PreviewFetch, PreviewSeedPanel, type PreviewSeedPanelProps, type PreviewSetup, ROOT_ID, RestSpecStore, type RestStoreConfig, SPEC_PAIR_FREQ, type SduiCatalog, SduiEditor, type SduiEditorProps, type SduiEditorView, type Selection, type SlotDescriptor, type SpecStore, type StateKeyEntry, type StateKeyIndex, type StateKeyNode, type StateKeyOrigin, type StoreCapabilities, StoreUnauthorizedError, StoreUnavailableError, StoreUnsupportedError, TEMPLATES, TEXT_CHILD, type TransformResult, type TreeRow, type TreeRowKind, TreeView, type TreeViewProps, type VersionExpectation, VersionMismatchError, ViewerView, type ViewerViewProps, type WriteOptions, addressOf, ancestorIdsOf, argsWrapperPage, bindingContextFor, breadcrumbOf, buildStateKeyIndex, builderFidelity, canDrop, canDropAt, canMoveTo, canRedo, canUndo, collectStateKeys, createBindingContext, createBindingSource, createDataPreviewAdapter, createEditorState, createEditorUseSpec, createRestSpecStore, describeChild, dialogOpenSeeds, dropFrequency, dropTargetsAround, duplicate, editorReducer, editorRegistry, emptyDoc, flattenTree, formatAction, formatActionList, formatValue, fromPage, getChild, getNode, gradeIssues, inDocumentOrder, insert, isDescendantOf, isDialogSpecId, isMultiSelection, isSelected, isTypingTarget, isValidPageId, looksLikeActionProp, move, parseSeedValue, patternParams, readActionList, recommendedChildren, redoLabel, remove, replaceChild, resolvePreviewAdapter, sameInsertionPoint, sameSpecMeaning, seedSignature, seedsOf, setChildren, setNodeKey, setPageMeta, setProp, setProps, setText, slotsOf, specOf, stateKeyStatus, suggestStateKeys, titleOf, toPage, toSpec, topmost, undoLabel, useUndoRedoShortcuts, walkDoc, writeActionList };
+export { ActionEditor, type ActionEditorProps, type ActionList, type ActionValue, type BindingContext, BindingEditor, type BindingEditorProps, type BindingSource, type BuilderChild, type BuilderDoc, type BuilderFidelity, type BuilderNode, type BuilderPageMeta, type BuilderText, BuilderView, type BuilderViewProps, COALESCE_WINDOW_MS, Canvas, type CanvasProps, type ChildLabel, DEFAULT_SLOT, DIALOG_PREFIX, type DropDomContext, type DropTarget, type DropVerdict, EMPTY_SELECTION, type EditorAction, type EditorState, EditorView, type EditorViewProps, FRAGMENT_PREFIX, type FlattenOptions, type GradeIssuesOptions, type GradedIssue, HISTORY_LIMIT, HistoryBar, type HistoryBarProps, type HistoryEntry, INITIAL_PREVIEW_SETUP, Inspector, type InspectorChange, type InspectorProps, type ManualSeed, type NodeId, PAGE_ID_PATTERN, PageExistsError, PageGoneError, PageIdConflictError, PageIdRejectedError, PageListView, type PageListViewProps, type PageMeta, type PageRecord, type PageRevision, type PageTemplate, Palette, type PaletteProps, type PreviewAdapterOptions, type PreviewEntityOption, type PreviewEntitySearch, type PreviewFetch, PreviewSeedPanel, type PreviewSeedPanelProps, type PreviewSetup, ROOT_ID, RestSpecStore, type RestStoreConfig, type RestStorePaths, SPEC_PAIR_FREQ, type SduiCatalog, SduiEditor, type SduiEditorProps, type SduiEditorView, type Selection, type SlotDescriptor, type SpecStore, type StateKeyEntry, type StateKeyIndex, type StateKeyNode, type StateKeyOrigin, type StoreCapabilities, StoreUnauthorizedError, StoreUnavailableError, StoreUnsupportedError, TEMPLATES, TEXT_CHILD, type TransformResult, type TreeRow, type TreeRowKind, TreeView, type TreeViewProps, type VersionExpectation, VersionMismatchError, ViewerView, type ViewerViewProps, type WriteOptions, addressOf, ancestorIdsOf, argsWrapperPage, bindingContextFor, breadcrumbOf, buildStateKeyIndex, builderFidelity, canDrop, canDropAt, canMoveTo, canRedo, canUndo, collectStateKeys, createBindingContext, createBindingSource, createDataPreviewAdapter, createEditorState, createEditorUseSpec, createRestSpecStore, describeChild, dialogOpenSeeds, dropFrequency, dropTargetsAround, duplicate, editorReducer, editorRegistry, emptyDoc, flattenTree, formatAction, formatActionList, formatValue, fromPage, getChild, getNode, gradeIssues, inDocumentOrder, insert, isDescendantOf, isDialogSpecId, isFragmentSpecId, isMultiSelection, isSelected, isTypingTarget, isValidPageId, looksLikeActionProp, move, parseSeedValue, pathFromView, patternParams, readActionList, recommendedChildren, redoLabel, remove, replaceChild, resolvePreviewAdapter, sameDropTarget, sameInsertionPoint, sameSpecMeaning, seedSignature, seedsOf, setChildren, setNodeKey, setPageMeta, setProp, setProps, setText, slotsOf, specOf, stateKeyStatus, suggestStateKeys, titleOf, toPage, toSpec, topmost, undoLabel, useUndoRedoShortcuts, viewFromPath, walkDoc, writeActionList };