@wipco/sdui-editor 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import * as react from 'react';
-import react__default from 'react';
-import { SpecIssue } from '@wipco/sdui';
+import * as React from 'react';
+import React__default from 'react';
+import { SduiRegistry, SduiAdapter, SduiCanSetting, SpecIssue, SduiPage, SduiPropValue, SduiChild } from '@wipco/sdui';
+import { SduiComponentMeta, SduiPropMeta } from '@wipco/sdui/meta';
 
 /**
  * 스펙 저장소 어댑터 계약.
@@ -276,11 +277,57 @@ interface SduiEditorProps {
     defaultView?: SduiEditorView;
     /** 편집기 자체 헤더(저장소 배지)를 그릴지. 소비 프로젝트 크롬이 이미 있으면 false */
     chrome?: boolean;
+    /**
+     * 스펙을 그릴 때 쓸 컴포넌트 어휘. **소비 프로젝트가 자기 것을 넣는 자리다.**
+     *
+     * 생략하면 라이브러리가 아는 66종(기본 39 + DS 6 + 표시 위젯 21)으로 그린다.
+     * 위젯은 지연 로드라 안 쓰면 내려오지 않는다(`editorRegistry` 주석 참고).
+     *
+     * 소비 프로젝트가 `createRegistry`로 어휘를 넓혔다면 **그 레지스트리를 그대로 넘긴다.**
+     * 그러지 않으면 앱 고유 이름(ERP의 `ExcelUploadCard`·`Logo` 등)이 편집 화면에서만
+     * 자리 표시로 나오고, 편집자는 자기가 고치는 화면이 실제로 어떻게 보이는지 모른 채
+     * 저장하게 된다.
+     *
+     * ```tsx
+     * import { registry } from './lib/sdui/registry';       // 앱이 이미 쓰는 그것
+     * <SduiEditor store={store} registry={registry} catalog={catalog} />
+     * ```
+     */
+    registry?: SduiRegistry;
+    /**
+     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 69종.
+     *
+     * `registry`를 넓혔다면 여기도 같이 넓혀야 한다 — 레지스트리는 "그릴 수 있는 이름",
+     * 이쪽은 "빌더가 프롭을 그릴 줄 아는 이름"이라 둘은 따로 논다.
+     * `{ ...allComponentMeta, ...myMeta }`처럼 합쳐 넘기면 된다.
+     */
+    catalog?: Record<string, SduiComponentMeta>;
     /**
      * 뷰어에서 스펙의 `navigate` 액션이 나왔을 때. 주지 않으면 뷰어 안에서 그 페이지를
      * 열어 본다(절대 URL은 무시한다 — 편집기를 마운트한 화면을 날려 버리지 않기 위해).
      */
     onNavigate?: (to: string) => void;
+    /**
+     * 뷰어("보기")가 쓸 호스트 연결점. **생략하면 캔버스와 같은 봉인 어댑터**다.
+     *
+     * 편집기의 세 화면 중 뷰어만 봉인되지 않아, 편집 화면 툴바의 "보기" 버튼 한 번으로
+     * `submitForm`의 DELETE가 운영 API까지 나간 적이 있다. 지금은 기본값이 막는다.
+     * 실제 데이터가 붙은 화면까지 보려는 호스트만 여기에 자기 어댑터를 준다.
+     *
+     * 캔버스(빌더)에는 이 통로를 열지 않는다 — 캔버스는 **저장도 안 된 편집 중 텍스트**를
+     * 그리는 자리라 호스트가 무엇을 주든 열려서는 안 된다.
+     *
+     * @see ViewerViewProps.adapter
+     */
+    viewerAdapter?: SduiAdapter;
+    /**
+     * 권한 판정 — 뷰어의 `Can` 게이트가 질의한다.
+     *
+     * 안 주면 모든 `<Can>`이 통과해, 실제로는 그 사용자에게 안 보였을 버튼이 "실제 모습
+     * 확인" 화면에 그려진다. 캔버스는 `Can`을 조건이 보이는 배지 컴포넌트로 갈아 끼우므로
+     * 이 값이 없어도 편집자를 오도하지 않는다 — 그래서 캔버스에는 넘기지 않는다.
+     */
+    can?: SduiCanSetting;
     className?: string;
 }
 /**
@@ -299,22 +346,40 @@ interface SduiEditorProps {
  * <SduiEditor store={store} />
  * ```
  */
-declare function SduiEditor({ store, view, onViewChange, defaultView, chrome, onNavigate, className, }: SduiEditorProps): react.JSX.Element;
+declare function SduiEditor({ store, view, onViewChange, defaultView, chrome, registry, catalog, onNavigate, viewerAdapter, can, className, }: SduiEditorProps): React.JSX.Element;
 
 interface PageListViewProps {
     store: SpecStore;
     onEdit: (id: string) => void;
     onPreview: (id: string) => void;
 }
-declare function PageListView({ store, onEdit, onPreview }: PageListViewProps): react.JSX.Element;
+declare function PageListView({ store, onEdit, onPreview }: PageListViewProps): React.JSX.Element;
 
 interface EditorViewProps {
     store: SpecStore;
     id: string;
     onBack: () => void;
     onPreview: (id: string) => void;
+    /**
+     * 이 화면(빌더 캔버스·JSON 미리보기)이 스펙을 그릴 때 쓸 레지스트리.
+     *
+     * 생략하면 {@link editorRegistry} — 라이브러리가 아는 어휘 66종이다. 소비 앱이
+     * `createRegistry`로 자기 컴포넌트를 얹었다면 **그것을 그대로 넘겨야** 편집 화면과
+     * 운영 화면이 같은 그림이 된다. 두 렌더러(빌더·미리보기)에 같은 값이 간다 —
+     * 한쪽만 넓으면 모드를 바꿀 때 화면이 달라진다.
+     */
+    registry?: SduiRegistry;
+    /**
+     * 팔레트·속성 패널이 볼 메타데이터. 생략하면 라이브러리 어휘 69종
+     * (`@wipco/sdui/meta`의 `allComponentMeta`).
+     *
+     * `registry`에 앱 고유 컴포넌트를 얹었다면 그 메타데이터도 여기 합쳐 넘겨야
+     * 팔레트에서 집을 수 있다. 레지스트리에만 있고 여기 없는 이름은 스펙에 있으면
+     * 그려지되 팔레트에는 안 나온다.
+     */
+    catalog?: Record<string, SduiComponentMeta>;
 }
-declare function EditorView({ store, id, onBack, onPreview }: EditorViewProps): react__default.JSX.Element;
+declare function EditorView({ store, id, onBack, onPreview, registry, catalog }: EditorViewProps): React__default.JSX.Element;
 
 interface ViewerViewProps {
     store: SpecStore;
@@ -329,16 +394,62 @@ interface ViewerViewProps {
      * 통째로 날아가고 저장 안 한 초안이 함께 사라진다.
      */
     onNavigate: (to: string) => void;
+    /**
+     * 렌더링 어휘. **캔버스와 같은 값을 받아야 한다** — 편집 중에는 그려지던 위젯이
+     * "보기"로 넘어가면 사라지는 것이 사용자에게는 저장이 깨진 것으로 보인다.
+     *
+     * 생략하면 {@link editorRegistry} 66종 — 캔버스의 기본값과 같은 값이다.
+     * 예전에는 여기가 비면 `SduiRenderer`의 기본값(`defaultRegistry` 39종)으로 떨어졌다.
+     * `SduiEditor` 셸이 `registry ?? editorRegistry`로 때워 두었지만 `ViewerView`는
+     * 개별 export라, **자기 셸을 짜서 단독 마운트한 소비자에게는 그 때움이 안 닿았다.**
+     * 때우는 자리를 셸에서 프롭 기본값으로 내린 이유가 그것이다.
+     */
+    registry?: SduiRegistry;
+    /**
+     * 호스트 연결점. **생략하면 캔버스와 같은 봉인 어댑터로 그린다.**
+     *
+     * 예전 기본값은 "아무것도 막지 않음"이었다. 그 선택의 근거는 "뷰어는 저장된 스펙을
+     * 실제 소비 화면처럼 보는 자리"였고 그 자체는 지금도 맞다. 틀린 것은 **주입 통로를
+     * 열어 두지 않은 채로 그 기본값을 골랐다는 점**이다 — 이 파일의 예전 주석은
+     * "소비 프로젝트가 어댑터를 주입해 원하는 만큼만 열어 주면 된다"고 적어 두었지만
+     * `ViewerViewProps`에도 `SduiEditorProps`에도 그 프롭이 없었다. 그래서 소비
+     * 프로젝트에는 열고 닫을 손잡이가 아예 없었고, 실측에서 편집 화면 툴바의 "보기"
+     * 버튼 한 번이 `DELETE /assets/AS-0042`와 `GET /assets/export`를 **운영 API로**
+     * 내보냈다. "본다"는 낱말이 붙은 자리가 실제로 지웠다.
+     *
+     * 그래서 기본값을 뒤집는다. 편집기의 세 화면(캔버스·JSON 미리보기·뷰어)은 모두
+     * "편집자의 특권 세션으로, 사용자가 그 동작을 하겠다고 밝힌 적 없이" 스펙을 그리는
+     * 자리다. 파괴적 기본값을 셋 중 하나만 남겨 둘 이유가 없다.
+     *
+     * 뷰어가 캔버스와 다른 점은 **어댑터가 아니라 렌더링 논리**에 있다 — 캔버스는
+     * `Show`·`Can`·`ForEach`를 조건 무시하고 펼치고 `Dialog`를 흐름 안에 눕히지만,
+     * 뷰어는 진짜 조건·진짜 모달로 그린다. 그 차이는 여기서 하나도 잃지 않는다.
+     *
+     * 실제 데이터까지 보고 싶은 호스트는 자기 어댑터를 주입한다. 그 선택은 호스트가
+     * 자기 위험 감수 범위를 알고 내리는 것이라 라이브러리 기본값이 대신 정하지 않는다.
+     */
+    adapter?: SduiAdapter;
+    /**
+     * 권한 판정 — 뷰어가 `SduiRenderer`에 그대로 넘긴다.
+     *
+     * 안 주면 렌더러가 "판정 없음"으로 보고 **모든 `<Can>`을 통과**시킨다(콘솔에 경고를
+     * 남긴다). 캔버스는 `Can`을 항상 펼치는 컴포넌트로 갈아 끼우고 "권한 | asset · create"
+     * 배지로 조건을 **보여 주므로** 편집자가 그 사실을 안다. 뷰어에는 그 배지가 없어서,
+     * 원래 안 보였어야 할 버튼이 조건 없이 그냥 그려진다 — "실제 모습 확인"이 목적인
+     * 화면에서 권한 재단만 빠진다.
+     */
+    can?: SduiCanSetting;
 }
 /**
  * 페이지 뷰어 — 저장된 스펙을 실제 소비 화면처럼 렌더링한다.
  *
- * 편집기 미리보기와 달리 **어댑터를 막지 않는다**. 여기서 보는 것은 편집 중인 텍스트가
- * 아니라 이미 저장된 스펙이고, 소비 프로젝트가 실제로 어떻게 그릴지 확인하는 자리다.
- * 다만 부작용(submitForm 등)은 진짜로 나가므로 소비 프로젝트가 어댑터를 주입해
- * 원하는 만큼만 열어 주면 된다.
+ * 캔버스와 다른 것은 **렌더링 논리**다: 조건(`Show`)·권한(`Can`)·반복(`ForEach`)이
+ * 실제로 판정되고 `Dialog`가 진짜 모달로 뜬다. 캔버스가 편집을 위해 일부러 무시하는
+ * 것들을 여기서 확인한다.
+ *
+ * 부작용 차단은 캔버스와 **같다**. {@link ViewerViewProps.adapter} 참고.
  */
-declare function ViewerView({ store, id, onBack, onEdit, onNavigate }: ViewerViewProps): react__default.JSX.Element;
+declare function ViewerView({ store, id, onBack, onEdit, onNavigate, registry, adapter: hostAdapter, can, }: ViewerViewProps): React__default.JSX.Element;
 
 /**
  * 새 페이지 생성 템플릿 — 스펙 문법 견본을 겸한다.
@@ -361,4 +472,1293 @@ type GradedIssue = SpecIssue & {
 };
 declare function gradeIssues(spec: unknown): GradedIssue[];
 
-export { EditorView, type EditorViewProps, type GradedIssue, PAGE_ID_PATTERN, PageExistsError, PageGoneError, PageIdConflictError, PageIdRejectedError, PageListView, type PageListViewProps, type PageMeta, type PageRecord, type PageRevision, type PageTemplate, RestSpecStore, type RestStoreConfig, SduiEditor, type SduiEditorProps, type SduiEditorView, type SpecStore, type StoreCapabilities, StoreUnauthorizedError, StoreUnavailableError, StoreUnsupportedError, TEMPLATES, type VersionExpectation, VersionMismatchError, ViewerView, type ViewerViewProps, type WriteOptions, createRestSpecStore, gradeIssues, isValidPageId, titleOf };
+/**
+ * 시각 빌더의 **문서 모델** — 편집 중인 페이지의 자료구조와 변형 연산.
+ *
+ * 이 파일에는 React도 DOM도 없다. 팔레트·캔버스·트리·속성 패널이 전부 여기 있는
+ * 순수 함수만 호출하도록 만든 것이라, 편집 규칙을 화면 없이 `node --test`로 검증할 수 있다.
+ * (실제로 그렇게 했다 — `test/builder-model.test.ts`)
+ *
+ * ## 왜 스펙(SduiPage)을 그대로 편집하지 않는가
+ *
+ * `SduiNode`에는 **안정적인 식별자가 없다.** `key`는 선택적이고(실측 3,124개 노드 중
+ * 149개에만 있다) 배열 인덱스는 형제를 하나만 지워도 전부 밀린다. 그런데 편집기는
+ * "지금 선택한 노드", "트리에서 펼쳐 둔 노드", "실행취소 후에도 같은 노드"를 계속
+ * 가리켜야 한다. 그래서 편집 중에는 **id가 박힌 별도 트리**({@link BuilderNode})를 쓰고,
+ * 렌더러·검증기·저장소에 넘길 때만 {@link toPage}로 스펙을 만든다.
+ *
+ * 후보 세 가지를 두고 이렇게 정했다.
+ *
+ * 1. **경로 기반**(`body[0].children[2]`) — 자료구조를 하나도 안 늘려도 되지만,
+ *    형제 재정렬·삽입·삭제마다 선택과 실행취소 기록이 통째로 어긋난다. 탈락.
+ * 2. **스펙에 id를 심기**(`props.__id`) — 저장하는 순간 운영 DB에 편집기 부산물이
+ *    들어간다. 렌더러가 모르는 프롭이라 컴포넌트에 그대로 흘러가기도 한다. 탈락.
+ * 3. **id를 가진 편집용 트리 + 스펙 투영** — 채택. id가 자료의 일부라 변형 연산이
+ *    전부 순수 함수가 되고(전역 id 발급기도 WeakMap 부작용도 없다), 텍스트 자식까지
+ *    id를 가질 수 있어 "카드 본문의 저 글자"를 트리에서 가리킬 수 있다.
+ *
+ * 3번의 유일한 대가는 투영 비용인데, {@link toPage}가 노드 단위로 결과를 캐시해서
+ * **바뀐 경로만 새 객체**가 되도록 맞춰 뒀다. 변형 연산이 구조 공유(structural sharing)를
+ * 지키므로 안 바뀐 `BuilderNode`는 참조가 그대로고, 그러면 캐시가 맞아 같은 `SduiNode`가
+ * 다시 나온다. 렌더러의 참조 동일성 기대가 그대로 유지된다.
+ *
+ * ## 슬롯 주소 통일
+ *
+ * 스펙은 기본 자식을 `children`에, 이름 붙은 자리를 `slots.<이름>`에 나눠 담는다.
+ * 편집기에서는 둘 다 "부모 · 슬롯 · 인덱스"라는 한 가지 주소로 다뤄야 드롭 처리와
+ * 트리 렌더가 두 벌이 되지 않는다. 그래서 내부에서는 기본 자식도 슬롯 하나로 보고
+ * {@link DEFAULT_SLOT} 키에 담는다. `$`로 시작해서 실제 슬롯 이름과 부딪히지 않는다
+ * (스펙의 슬롯 이름은 프롭 이름이라 식별자 문법을 따른다).
+ */
+
+/**
+ * 편집기가 아는 컴포넌트 메타데이터 전부 — 라이브러리 어휘에 소비 앱 것을 합친 것.
+ *
+ * ## 왜 인자로 들고 다니는가
+ *
+ * 이 모듈의 판정 함수는 전부 **순수 함수**다. React 컨텍스트를 쓸 수 없고, 모듈 전역에
+ * 담아 두면 편집기를 두 개 띄웠을 때 서로를 덮는다(테스트 격리도 깨진다). 그래서
+ * 후행 선택 인자로 받아 아래로 넘긴다 — 장황하지만 이것만이 두 인스턴스가 서로 다른
+ * 어휘를 볼 수 있는 유일한 방법이다.
+ *
+ * 기본값(`allComponentMeta`)을 남겨 둔 것은 하위 호환 때문이지, 안 넘겨도 된다는 뜻이
+ * **아니다**. 기본값이 있으면 배선을 빠뜨려도 조용히 라이브러리 어휘로 돌아가 사고가
+ * 드러나지 않으므로, 편집기 안에서 인자를 빠뜨린 호출부가 있으면 실패하는 소스 스캔
+ * 테스트(`test/catalog-wiring.test.ts`)로 따로 막는다.
+ */
+type SduiCatalog = Record<string, SduiComponentMeta>;
+/**
+ * 편집 세션 안에서만 의미가 있는 노드 식별자. 저장되는 스펙에는 나가지 않는다.
+ * 브랜드 타입으로 만들지 않은 이유는 이 값이 곧장 React key·DOM data 속성·Map 키로
+ * 흘러가기 때문이다 — 그 자리마다 캐스팅을 요구하면 얻는 것보다 잃는 게 많다.
+ */
+type NodeId = string;
+/** 페이지 본문(`body`)을 가리키는 가상 부모. 드롭 대상으로 최상위를 지목할 때 쓴다. */
+declare const ROOT_ID: NodeId;
+/** 기본 자식(`children`)을 담는 슬롯 키. 스펙의 슬롯 이름과 부딪히지 않도록 `$`로 시작한다. */
+declare const DEFAULT_SLOT = "$children";
+/**
+ * 문자열 자식을 컴포넌트 이름 자리에 놓아야 할 때 쓰는 표식
+ * (드롭 판정·빈도표의 키). 실측 스펙의 자식 3,124건 중 1,163건이 문자열이라
+ * "텍스트도 드롭 대상"을 1급으로 다루지 않으면 규칙에 구멍이 생긴다.
+ */
+declare const TEXT_CHILD = "#text";
+/** 드롭·삽입 지점. `parent`가 {@link ROOT_ID}면 페이지 본문이다. */
+interface DropTarget {
+    readonly parent: NodeId;
+    readonly slot: string;
+    /** 삽입 위치. 슬롯 길이를 넘으면 끝에 붙는다(음수는 0). */
+    readonly index: number;
+}
+interface BuilderText {
+    readonly kind: 'text';
+    readonly id: NodeId;
+    readonly text: string;
+}
+interface BuilderNode {
+    readonly kind: 'node';
+    readonly id: NodeId;
+    /** 스펙의 `component`. 레지스트리에 없는 이름일 수도 있다(소비 앱이 얹은 컴포넌트). */
+    readonly component: string;
+    /** 스펙의 `key` — React key. 편집기가 만드는 값이 아니라 작성자가 정한 값이다. */
+    readonly key?: string;
+    readonly props: Readonly<Record<string, SduiPropValue>>;
+    /** 비어 있는 슬롯은 키 자체를 두지 않는다 — 투영 결과에 `slots: { footer: [] }`가 남지 않게. */
+    readonly slots: Readonly<Record<string, readonly BuilderChild[]>>;
+}
+type BuilderChild = BuilderNode | BuilderText;
+/**
+ * `body`를 뺀 페이지 필드.
+ *
+ * 인덱스 시그니처를 교차시켜 **타입에 없는 필드도 담기게** 했다. 실측 스펙에는
+ * `SduiPage`에 없는 `require`(페이지 단위 권한 게이트, 소비 앱이 해석한다)가 들어 있고,
+ * 빌더가 이런 필드를 조용히 떨어뜨리면 편집 한 번에 페이지 권한이 풀린다.
+ */
+type BuilderPageMeta = Omit<SduiPage, 'body'> & Record<string, unknown>;
+interface BuilderDoc {
+    readonly meta: BuilderPageMeta;
+    readonly body: readonly BuilderChild[];
+    /**
+     * 다음에 발급할 id 번호. **문서가 들고 있는 이유**는 변형 연산을 순수 함수로 두기
+     * 위해서다 — 모듈 전역 카운터를 쓰면 같은 입력에 다른 결과가 나와 테스트가 불안정해지고,
+     * 문서를 두 개 열면 서로의 id를 밀어 버린다.
+     */
+    readonly nextId: number;
+}
+/** 변형 연산의 결과. 실패해도 던지지 않는다 — 편집기는 드롭 실패를 예외로 다루지 않는다. */
+interface TransformResult {
+    readonly doc: BuilderDoc;
+    /** 문서가 실제로 바뀌었는가. false면 호출부는 실행취소 기록을 쌓지 않는다. */
+    readonly changed: boolean;
+    /** 이번 변형이 만들거나 옮긴 노드 — 편집기가 이어서 선택한다. */
+    readonly affected: readonly NodeId[];
+    /** 거절 사유(한국어). 없으면 "바뀐 게 없었다"는 뜻일 뿐이다. */
+    readonly rejected?: string;
+}
+/**
+ * 스펙을 편집 트리로 연다. id는 문서 순서대로 `n1`부터 붙는다 —
+ * 결정적이라 같은 스펙을 두 번 열면 같은 id가 나오고, 테스트가 흔들리지 않는다.
+ *
+ * 스펙이 아예 객체가 아니어도 빈 문서를 돌려준다. "열 수 없는 스펙"을 예외로 만들면
+ * 편집기가 그 페이지를 고칠 유일한 창구를 스스로 닫는 셈이다.
+ */
+declare function fromPage(page: unknown): BuilderDoc;
+/** 노드 하나만 스펙으로. 미리보기·복사·JSON 편집에 쓴다. */
+declare function toSpec(child: BuilderChild): SduiChild;
+/**
+ * 편집 트리를 스펙으로 되돌린다. 렌더러·`validateSpec`·저장소에 넘기는 유일한 통로다.
+ * 안 바뀐 가지는 이전 호출과 **같은 객체**가 나온다(위 캐시 참고).
+ *
+ * 딱 하나 정규화하는 것이 있다: **빈 `children: []`와 빈 슬롯은 키째로 사라진다.**
+ * 렌더러에게 "빈 배열"과 "없음"은 같은 뜻이라 화면이 달라지지 않고, 남겨 두면
+ * 슬롯을 비울 때마다 `slots: { footer: [] }` 같은 껍데기가 스펙에 쌓인다.
+ * (실측 스펙 84개에는 빈 컨테이너가 하나도 없어서, 기존 페이지를 열고 저장해도
+ *  이 정규화로 바뀌는 바이트는 없다 — 확인했다.)
+ */
+declare function toPage(doc: BuilderDoc): SduiPage;
+/** 빈 문서. 새 페이지를 만들 때 쓴다. */
+declare function emptyDoc(title?: string): BuilderDoc;
+/** 문서 전체를 부모·슬롯·인덱스와 함께 훑는다. `visit`이 false를 돌려주면 그 가지는 건너뛴다. */
+declare function walkDoc(doc: BuilderDoc, visit: (child: BuilderChild, addr: DropTarget) => void | boolean): void;
+/** id로 자식(노드 또는 텍스트)을 찾는다. */
+declare function getChild(doc: BuilderDoc, id: NodeId): BuilderChild | null;
+/** id로 컴포넌트 노드를 찾는다. 텍스트 자식이면 null. */
+declare function getNode(doc: BuilderDoc, id: NodeId): BuilderNode | null;
+/** 자식이 놓인 자리. 없으면 null. 최상위 자식은 `parent`가 {@link ROOT_ID}다. */
+declare function addressOf(doc: BuilderDoc, id: NodeId): DropTarget | null;
+/** 루트에 가까운 순서의 조상 id 목록(자기 자신은 빼고). */
+declare function ancestorIdsOf(doc: BuilderDoc, id: NodeId): readonly NodeId[];
+/** `id`가 `ancestor`의 자손인가(자기 자신은 false). */
+declare function isDescendantOf(doc: BuilderDoc, ancestor: NodeId, id: NodeId): boolean;
+/** 여러 id를 문서 순서로 정렬한다. 다중 선택을 옮기거나 지울 때 순서가 뒤집히지 않게. */
+declare function inDocumentOrder(doc: BuilderDoc, ids: readonly NodeId[]): readonly NodeId[];
+/**
+ * 이미 선택된 id 중 **조상이 함께 선택된 것**을 걷어낸다.
+ * 부모와 자식을 같이 잡고 옮기면 자식이 두 번 이동해 사라지므로, 이동·삭제·복제는
+ * 전부 이 결과를 대상으로 삼는다.
+ */
+declare function topmost(doc: BuilderDoc, ids: readonly NodeId[]): readonly NodeId[];
+/**
+ * 스펙 조각을 대상 자리에 넣는다. 팔레트 드롭(`meta.preset`)과 붙여넣기가 같은 길을 쓴다.
+ * 어휘 규칙 판정({@link canDrop})은 **호출부의 몫**이다 — 트리에서 강제로 넣어야 하는
+ * 상황(잘못 만들어진 스펙 고치기)까지 여기서 막으면 편집기가 자기 발을 묶는다.
+ */
+declare function insert(doc: BuilderDoc, target: DropTarget, specs: readonly SduiChild[]): TransformResult;
+/** 노드를 지운다. 조상이 함께 선택돼 있으면 조상만 지운다. */
+declare function remove(doc: BuilderDoc, ids: readonly NodeId[]): TransformResult;
+/**
+ * 노드를 다른 자리로 옮긴다.
+ *
+ * 두 가지가 조용히 틀리기 쉬워 따로 다룬다.
+ * - **자기 자손 안으로 옮기기**: 트리에서 뿌리째 사라진다. 막는다.
+ * - **같은 슬롯 안 재정렬**: `index`는 *빼내기 전* 기준이라, 앞쪽에서 빠진 개수만큼
+ *   당겨 줘야 한다. 안 그러면 "한 칸 위로"가 제자리걸음이 된다.
+ */
+declare function move(doc: BuilderDoc, ids: readonly NodeId[], target: DropTarget): TransformResult;
+/**
+ * 노드를 바로 뒤에 복제한다. **id는 전부 새로 발급한다** — 원본과 사본이 같은 id를 쓰면
+ * 선택이 두 곳을 가리키고 이후 편집이 엉뚱한 쪽에 적용된다.
+ */
+declare function duplicate(doc: BuilderDoc, ids: readonly NodeId[]): TransformResult;
+/** 프롭 하나를 바꾼다. `undefined`를 주면 프롭을 **지운다**(기본값으로 되돌리기). */
+declare function setProp(doc: BuilderDoc, id: NodeId, name: string, value: SduiPropValue | undefined): TransformResult;
+/**
+ * 여러 프롭을 한 번에. 크기 조정 핸들처럼 두 프롭이 같이 움직이는 자리에서
+ * 실행취소가 반쪽만 되돌리지 않게 하려면 이쪽을 써야 한다.
+ */
+declare function setProps(doc: BuilderDoc, id: NodeId, patch: Readonly<Record<string, SduiPropValue | undefined>>): TransformResult;
+/** React key(스펙의 `key`)를 바꾼다. 빈 문자열·undefined면 지운다. */
+declare function setNodeKey(doc: BuilderDoc, id: NodeId, key: string | undefined): TransformResult;
+/**
+ * 슬롯의 자식 목록을 통째로 교체한다. 붙여넣기·JSON 편집·"이 슬롯 비우기"가 쓴다.
+ * 넘긴 조각에는 **새 id가 붙는다** — 기존 자식을 그대로 두려면 {@link move}를 써라.
+ */
+declare function setChildren(doc: BuilderDoc, parent: NodeId, slot: string, specs: readonly SduiChild[]): TransformResult;
+/** 텍스트 자식의 내용을 바꾼다. */
+declare function setText(doc: BuilderDoc, id: NodeId, text: string): TransformResult;
+/**
+ * 노드 하나를 다른 스펙으로 갈아 끼운다(고급 모드의 "이 노드만 JSON으로 편집").
+ * 새 id가 붙으므로 호출부는 결과의 `affected`로 선택을 옮겨야 한다.
+ */
+declare function replaceChild(doc: BuilderDoc, id: NodeId, spec: SduiChild): TransformResult;
+/**
+ * 페이지 수준 필드(title·subtitle·urlState·subscribe·그리고 타입에 없는 `require` 등)를 바꾼다.
+ * `undefined`를 주면 필드를 지운다.
+ */
+declare function setPageMeta(doc: BuilderDoc, patch: Readonly<Record<string, unknown>>): TransformResult;
+interface DropVerdict {
+    /** 놓을 수 있는가. **막는 것은 렌더러가 절대 그리지 못하는 조합뿐**이다. */
+    readonly ok: boolean;
+    /** 실측 스펙 84개에서 이 자리에 쓰인 횟수. 0은 "전례 없음"이지 "금지"가 아니다. */
+    readonly seen: number;
+    /** 강조해서 안내할 만한 자리인가(= ok이고 전례가 있다). */
+    readonly recommended: boolean;
+    /** 한국어 사유. ok=false면 막은 이유, ok=true면 주의 문구(없을 수 있다). */
+    readonly reason?: string;
+}
+/**
+ * 판정에 쓸 DOM 맥락. 전부 선택 항목이다 — 컴포넌트 이름만 아는 호출부
+ * (팔레트·캔버스의 슬롯 칩)도 그대로 쓸 수 있어야 하기 때문이다.
+ *
+ * 맥락이 없으면 요소를 바꾸는 프롭(`Text.as`·`Button.as`)을 못 읽어 **구현의 기본값**으로
+ * 본다. 실측 스펙에서 `as`를 준 자리는 `Text as="span"` 69회와 `as="p"` 3회뿐이고
+ * 둘 다 flow를 못 담는 것은 같아서, 기본값(`<p>`)으로 봐도 "넣지 마라"는 답이 바뀌지 않는다.
+ * `as="div"`처럼 판정이 실제로 뒤집히는 값은 실측에 없고, 있더라도 손해는 팔레트가 한 칸
+ * 더 막는 정도다(클릭 삽입은 막힌 자리를 만나면 형제로 넣는다). 진짜 드롭이 지나는
+ * {@link canDropAt}·{@link canMoveTo}는 문서에서 프롭을 읽으므로 정확하다.
+ */
+interface DropDomContext {
+    /** 부모 노드의 프롭 — `Text.as`처럼 요소를 바꾸는 프롭을 읽는다. */
+    readonly parentProps?: Readonly<Record<string, SduiPropValue>>;
+    /** 놓으려는 노드의 프롭. 팔레트 드롭이면 preset의 프롭이다. */
+    readonly childProps?: Readonly<Record<string, SduiPropValue>>;
+    /** 부모보다 위쪽 조상들이 만든 호스트 요소들(바깥→안쪽). `fragment`는 들어 있지 않다. */
+    readonly ancestorHosts?: readonly string[];
+}
+/**
+ * 이 조합을 놓아도 되는가.
+ *
+ * ## 화이트리스트를 쓰지 않는 이유 (실측)
+ *
+ * 스펙 84개에 나타난 부모→자식 조합은 **232종**(슬롯까지 구분하면 242종)이고, 그중
+ * 컴포넌트 이름이 이 라이브러리 어휘 69종 밖인 것도 스물 몇 가지다(소비 앱이 레지스트리에
+ * 얹은 `ExcelUploadCard`·`ApprovalStepper` 같은 것들). 손으로 유지되는 허용 목록은
+ * 하루면 낡는다. 그래서 **막는 규칙은 최소로, 나머지는 추천으로** 나눴다.
+ *
+ * ## 막는 것 (전부 "렌더러가 그리지 않음"이 근거다. 실측 위반 0건)
+ *
+ * - `children.accepts === false`인 부모의 기본 슬롯 — Table·Tabs·PageHead처럼
+ *   자식을 아예 렌더하지 않는 컴포넌트. 넣으면 조용히 사라진다.
+ * - `text === false`인 자리에 문자열 — 같은 이유.
+ * - 메타데이터에 없는 슬롯 이름 — 렌더러가 그 이름을 프롭으로 넘기고 컴포넌트가 무시한다.
+ * - `children.deny` — 메타데이터가 명시적으로 "안 된다"고 적어 둔 것.
+ * - **브라우저 파서가 태그를 강제로 닫는 DOM 중첩** — `<p>` 안의 `<hr>`, 버튼 안의 버튼 등.
+ *   스펙이 말한 구조가 화면에 나오지 않는다({@link domNesting}). 실측 위반 0건.
+ *
+ * ## 막지 않고 경고만 하는 것 (실측이 규칙을 반증했다)
+ *
+ * - `slots[].allow` 화이트리스트 — 실측이 이미 어긴다(`Card.actions`에 Icon 6회,
+ *   `SearchResults.headerActions`에 Text 1회). 잘 도는 화면을 편집기가 거절하면 안 된다.
+ * - `slotOnly`(Actions) — 슬롯 밖에서도 4번 쓰인다.
+ * - **콘텐츠 모델만 어기는 DOM 중첩** — `<span>` 안의 `<div>` 같은 것. 실측 7건.
+ * - 메타데이터를 모르는 컴포넌트 — **판단 근거가 없다는 이유로 막지 않는다.**
+ *   `dom` 메타가 없는 컴포넌트도 같다.
+ *
+ * @param parent 부모 컴포넌트 이름. `null`이면 페이지 본문(최상위).
+ * @param child  자식 컴포넌트 이름. 문자열 자식이면 {@link TEXT_CHILD}.
+ * @param slot   이름 붙은 슬롯. 생략하거나 {@link DEFAULT_SLOT}이면 기본 자식 자리.
+ * @param ctx    DOM 중첩을 조상까지 보려면 주는 맥락({@link canDropAt}이 문서에서 만들어
+ *               넘긴다). 없으면 부모 한 칸만 보고, 요소는 구현의 기본값으로 본다.
+ * @param catalog 소비 앱 어휘를 합친 카탈로그({@link SduiCatalog}). 안 넘기면 라이브러리
+ *               어휘만 보므로, 앱 고유 컴포넌트는 "규칙을 알 수 없음"으로 떨어져 전부 통과한다.
+ */
+declare function canDrop(parent: string | null, child: string, slot?: string, ctx?: DropDomContext, catalog?: SduiCatalog): DropVerdict;
+/**
+ * 문서 맥락에서의 드롭 판정 — 부모 컴포넌트 이름을 문서에서 읽어 {@link canDrop}에 넘긴다.
+ *
+ * DOM 중첩은 **부모만 봐서는 모자란다**(`Text > Badge > Divider`는 `<p>` 안의 `<hr>`이다).
+ * 문서가 있는 이 경로에서만 조상 요소 체인과 부모의 프롭까지 넘겨 준다.
+ *
+ * @param childProps 놓으려는 노드의 프롭. 팔레트 드롭이면 preset의 프롭,
+ *                   이동이면 옮기는 노드의 프롭이다(`Text.as` 같은 것을 읽는다).
+ */
+declare function canDropAt(doc: BuilderDoc, target: DropTarget, child: string, childProps?: Readonly<Record<string, SduiPropValue>>, catalog?: SduiCatalog): DropVerdict;
+/**
+ * 이미 문서에 있는 노드를 옮겨도 되는가. 어휘 규칙에 **순환 검사**를 얹는다 —
+ * 자기 자손 안으로 옮기면 트리에서 뿌리째 사라진다.
+ */
+declare function canMoveTo(doc: BuilderDoc, ids: readonly NodeId[], target: DropTarget, catalog?: SduiCatalog): DropVerdict;
+/** 실측 빈도 조회. 슬롯을 준 조합이 0이면 슬롯을 뺀 조합으로 한 번 더 본다. */
+declare function dropFrequency(parent: string | null, child: string, slot?: string): number;
+/**
+ * 이 자리에 실제로 자주 놓이는 컴포넌트를 많은 순으로. 팔레트 정렬·"빠른 추가" 메뉴용이다.
+ * 막히는 조합은 빼고 돌려준다.
+ */
+declare function recommendedChildren(parent: string | null, slot?: string, limit?: number, catalog?: SduiCatalog): ReadonlyArray<{
+    component: string;
+    seen: number;
+}>;
+/**
+ * ERP 스펙 84개에서 뽑은 **부모→자식 실사용 빈도**.
+ *
+ *   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…)이 섞여 있는데
+ * 일부러 남겨 뒀다 — 소비 앱이 레지스트리에 얹은 컴포넌트도 편집 대상이고,
+ * 이 표는 **금지 목록이 아니라 추천 근거**라서 모르는 이름이 있어도 해롭지 않다.
+ *
+ * 낡는 데이터다. 스펙이 크게 바뀌면 위 쿼리로 다시 뽑아 갈아 끼우면 되고,
+ * 갈아 끼우지 않아도 드롭이 막히지는 않는다(추천이 낡을 뿐이다).
+ */
+declare const SPEC_PAIR_FREQ: Readonly<Record<string, number>>;
+
+/**
+ * 빌더의 **편집 세션 상태** — 문서 + 선택 + 실행취소.
+ *
+ * React가 없다. 순수 리듀서라서 화면 없이 시나리오를 그대로 돌려 볼 수 있고,
+ * 화면 쪽은 `useReducer(editorReducer, createEditorState(spec))` 한 줄이면 된다.
+ * 상태 관리 라이브러리를 얹지 않은 이유도 같다 — 이 규모에서 얻는 것보다
+ * "편집 규칙이 어디 사는지"가 흐려지는 손해가 크다.
+ *
+ * ## 역할 분담
+ *
+ * 변형은 전부 `model.ts`가 하고, 여기서는 **그 결과를 기록**만 한다.
+ * 호출부는 이렇게 쓴다:
+ *
+ *     dispatch({
+ *       type: 'apply',
+ *       result: setProp(state.doc, id, 'title', next),
+ *       label: '제목 변경',
+ *       coalesce: `prop:${id}:title`,
+ *     });
+ *
+ * 리듀서가 `model`을 직접 부르지 않게 한 것은 의도적이다. 변형이 늘 때마다
+ * 액션 타입을 늘리면 리듀서가 편집 규칙의 두 번째 사본이 되고, 두 사본은 반드시 어긋난다.
+ */
+
+/**
+ * 지금 **무엇을 고치고**(ids·primary) **어디에 넣나**(insertAt).
+ *
+ * ## 왜 삽입 지점이 여기 있는가
+ *
+ * 둘은 뜻이 다르다. 선택은 노드를 가리키고, 삽입 지점은 노드가 아니라 **자리**를
+ * 가리킨다(`부모·슬롯·위치`). 트리의 슬롯 행 — 실측 최다 슬롯 `Dialog.footer`가
+ * 227회다 — 이 바로 그 경우다: 고를 노드는 없고 넣을 자리만 있다. 그래서 `ids`에
+ * 담을 수 없고 `DropTarget`으로 따로 든다.
+ *
+ * 그런데도 **한 값 안에** 둔 이유는 둘이 늘 함께 바뀌기 때문이다. 별도 상태로 나누면
+ * "슬롯 행을 골랐다"가 두 액션(선택 갱신 + 삽입 지점 갱신)이 되고, 그 둘 사이에는
+ * 반드시 어긋난 순간이 생긴다 — 옛 삽입 지점 + 새 선택으로 팔레트가 엉뚱한 자리에
+ * 넣는 사고가 정확히 그 틈에서 난다. 한 값이면 리듀서가 그 조합을 원자적으로 보장하고,
+ * 이미 `selection`을 받고 있는 화면(팔레트·캔버스·속성)이 배선 없이 같은 답을 본다.
+ */
+interface Selection {
+    /** 선택된 노드 전부. 문서 순서를 유지한다. */
+    readonly ids: readonly NodeId[];
+    /**
+     * 속성 패널이 보는 노드. 다중 선택에서도 "지금 편집 중인 하나"는 있어야 한다
+     * (없으면 패널이 매번 무엇을 띄울지 자기 규칙을 만들게 된다).
+     */
+    readonly primary: NodeId | null;
+    /**
+     * 사용자가 **직접 지목한** 삽입 지점. 팔레트 클릭·붙여넣기가 여기에 넣는다.
+     *
+     * `null`이면 "지목한 자리 없음"이고, 그때는 넣는 쪽이 선택에서 자리를 추정한다
+     * (팔레트의 규칙: 선택한 노드가 받아 주면 그 안, 아니면 그 뒤 형제).
+     * 지목한 자리는 추정보다 **언제나 우선**한다 — 사용자가 방금 손으로 짚은 자리다.
+     */
+    readonly insertAt: DropTarget | null;
+}
+declare const EMPTY_SELECTION: Selection;
+declare function isSelected(selection: Selection, id: NodeId): boolean;
+/** 다중 선택인가 — 정렬 도구·일괄 삭제 버튼을 켜는 조건. */
+declare function isMultiSelection(selection: Selection): boolean;
+/** 같은 자리를 가리키는가. 삽입 지점은 값이라 참조 비교로는 헛된 리렌더가 난다. */
+declare function sameInsertionPoint(a: DropTarget | null, b: DropTarget | null): boolean;
+/**
+ * 한 덩어리로 묶을 시간 창(ms).
+ *
+ * 실행취소의 단위가 이 파일에서 제일 손이 많이 간 부분이다. 한 글자마다 쌓으면
+ * Ctrl+Z를 스무 번 눌러야 문장 하나가 지워지고, 편집 세션 전체를 한 덩어리로 묶으면
+ * 되돌리는 순간 30분치가 날아간다. 그래서 두 장치를 뒀다.
+ *
+ * 1. **coalesce 키** — 같은 대상의 같은 프롭을 연달아 바꾸면 하나로 합친다.
+ *    이 창을 넘겨 손이 멈추면 다음 입력부터 새 덩어리가 된다. 700ms는 사람이
+ *    "이어서 치는 중"이라고 느끼는 대략의 상한이다(타자 사이 간격보다는 넉넉하고,
+ *    생각하고 다시 치는 간격보다는 짧다).
+ * 2. **명시적 트랜잭션** — 드래그처럼 시작과 끝을 아는 조작은 시간에 맡기지 않는다.
+ *    `txn: begin`으로 열고 `end`로 닫으면 그 사이가 통째로 한 덩어리다.
+ *    크기 조정 핸들을 1초 넘게 끌어도 되돌리기는 한 번이다.
+ *
+ * 구조 변경(삽입·이동·삭제·복제)은 **절대 합치지 않는다.** 되돌리는 사람이
+ * "방금 그 하나"를 기대하기 때문이다.
+ */
+declare const COALESCE_WINDOW_MS = 700;
+/** 기록 상한. 문서가 구조 공유라 한 칸의 비용이 작아 넉넉히 잡았다. */
+declare const HISTORY_LIMIT = 200;
+interface HistoryEntry {
+    /** 이 변경 **직전**의 문서. 실행취소는 여기로 돌아간다. */
+    readonly doc: BuilderDoc;
+    /** 직전의 선택 — 되돌렸을 때 보고 있던 자리로 같이 돌아가야 납득이 간다. */
+    readonly selection: Selection;
+    /** 사람이 읽는 한국어 이름("카드 삭제"). 실행취소 메뉴에 그대로 나간다. */
+    readonly label: string;
+    /** 같은 값이 연달아 오면 합친다. null이면 절대 합치지 않는다. */
+    readonly coalesceKey: string | null;
+    /** 마지막으로 합쳐진 시각(ms). 시간 창 판정에만 쓴다. */
+    readonly at: number;
+}
+/** 진행 중인 트랜잭션 — 드래그 한 번을 한 칸으로 묶는다. */
+interface PendingTxn {
+    readonly doc: BuilderDoc;
+    readonly selection: Selection;
+    readonly label: string;
+}
+interface EditorState {
+    readonly doc: BuilderDoc;
+    readonly selection: Selection;
+    /** 캔버스/트리 호버. 둘이 같은 값을 보므로 한쪽에 올리면 다른 쪽도 밝아진다. */
+    readonly hover: NodeId | null;
+    /** 드래그 중 미리보기 자리. 드롭 선을 그리는 쪽이 읽는다. */
+    readonly dropHint: DropTarget | null;
+    readonly past: readonly HistoryEntry[];
+    readonly future: readonly HistoryEntry[];
+    readonly pending: PendingTxn | null;
+    /** 마지막 저장 이후 문서가 바뀌었는가. 저장 버튼과 이탈 경고가 읽는다. */
+    readonly dirty: boolean;
+}
+declare function createEditorState(spec: unknown): EditorState;
+/** 저장·미리보기·검증에 넘길 스펙. 안 바뀐 가지는 이전과 같은 객체다. */
+declare function specOf(state: EditorState): SduiPage;
+declare function canUndo(state: EditorState): boolean;
+declare function canRedo(state: EditorState): boolean;
+/** 실행취소/다시실행 버튼의 툴팁("실행취소: 카드 삭제"). */
+declare function undoLabel(state: EditorState): string | null;
+declare function redoLabel(state: EditorState): string | null;
+type EditorAction = 
+/**
+ * 선택을 통째로 바꾼다.
+ *
+ * `insertAt`을 함께 주면 "이 노드를 고른 채 저 자리에 넣는다"가 한 번에 선다
+ * (트리의 슬롯 행 클릭). 주지 않으면 삽입 지점은 **비워진다** — 다른 곳을 고르고도
+ * 이전 슬롯이 남아 있으면 팔레트가 엉뚱한 자리에 넣는다.
+ */
+{
+    type: 'select';
+    ids: readonly NodeId[];
+    primary?: NodeId | null;
+    insertAt?: DropTarget | null;
+}
+/** Ctrl/⌘ 클릭 — 있으면 빼고 없으면 더한다. 삽입 지점은 놓아준다(노드를 고르는 조작이다). */
+ | {
+    type: 'selectToggle';
+    id: NodeId;
+} | {
+    type: 'hover';
+    id: NodeId | null;
+} | {
+    type: 'dropHint';
+    target: DropTarget | null;
+}
+/**
+ * `model.ts`의 변형 결과를 반영한다.
+ * - `label`    실행취소 메뉴에 나갈 한국어 이름
+ * - `coalesce` 같은 값이 연달아 오면 한 칸으로 합친다(타이핑·슬라이더)
+ * - `select`   기본 `affected` — 삽입/복제 직후 새 노드를 선택한다
+ */
+ | {
+    type: 'apply';
+    result: TransformResult;
+    label: string;
+    coalesce?: string;
+    select?: 'affected' | 'keep' | 'clear';
+}
+/** 드래그처럼 경계를 아는 조작을 한 칸으로 묶는다. */
+ | {
+    type: 'txn';
+    phase: 'begin';
+    label: string;
+} | {
+    type: 'txn';
+    phase: 'end' | 'cancel';
+} | {
+    type: 'undo';
+} | {
+    type: 'redo';
+}
+/** 고급 모드(JSON 편집기)가 스펙을 통째로 갈아 끼운다. */
+ | {
+    type: 'replaceSpec';
+    spec: unknown;
+    label: string;
+}
+/** 저장 성공 — dirty를 내린다. 기록은 그대로 둔다(저장 후에도 되돌릴 수 있어야 한다). */
+ | {
+    type: 'markSaved';
+};
+declare function editorReducer(state: EditorState, action: EditorAction, now?: number): EditorState;
+
+/**
+ * 시각 페이지 빌더의 **셸** — 팔레트·캔버스·속성·트리를 한 화면에 앉히고,
+ * 그 넷이 공유하는 편집 상태(`editorReducer`) 하나를 들고 있는다.
+ *
+ * 이 파일이 스스로 하는 일은 넷뿐이다. 나머지는 조각들의 몫이다.
+ *
+ *  1. **자리 배치** — 넷을 어디에 두고, 좁아지면 무엇을 접을 것인가.
+ *  2. **다리 놓기** — 속성 패널의 `onRequestBinding`을 바인딩·액션 편집기로 잇는다.
+ *     둘은 서로를 모르게 만들어져 있어(각자 다른 담당) 접합은 셸의 일이다.
+ *  3. **바깥과의 왕복** — 스펙을 받아 열고, 편집이 일어나면 스펙을 돌려준다.
+ *  4. **표현 가능성 판정** — 빌더가 그대로 왕복시키지 못하는 스펙을 미리 가려낸다
+ *     ({@link builderFidelity}). 이 판정을 보고 셸을 여는 쪽(EditorView)이 JSON으로 돌린다.
+ *
+ * ## 왜 스펙을 "비제어"로 받는가
+ *
+ * 문서는 편집 트리(`BuilderDoc`)로 살아 있고 스펙은 그 투영이다. 바깥이 준 `spec`을
+ * 매 렌더 반영하면 편집 한 번마다 문서를 새로 만드는 셈이라 선택·실행취소·트리 펼침이
+ * 통째로 날아간다. 그래서 `spec`은 **마운트 시점과 `syncKey`가 바뀔 때만** 읽는다.
+ * 바깥(서버 재로딩·JSON 모드 복귀)이 내용을 갈아끼웠다는 사실은 그쪽만 아는 정보라,
+ * 값이 아니라 키로 받는다.
+ */
+
+/**
+ * 두 스펙이 **같은 페이지를 뜻하는가.** 키 순서와 빈 컨테이너 차이는 무시한다.
+ *
+ * 빌더는 편집할 때마다 편집 트리에서 스펙을 다시 찍어 내므로 키 순서가 저장본과
+ * 달라진다(`{props, children, component}` → `{component, props, slots, children}`).
+ * 그 차이를 "바뀌었다"로 세면 되돌리기로 원래대로 돌려 놔도 "저장 안 됨"이 안 꺼진다.
+ */
+declare function sameSpecMeaning(a: unknown, b: unknown): boolean;
+interface BuilderFidelity {
+    /** 빌더로 열었다 저장해도 내용이 그대로인가. */
+    readonly ok: boolean;
+    /** ok=false일 때 어디가 달라지는지. 최대 6건까지만 센다(안내 문구가 목적이라). */
+    readonly issues: readonly string[];
+}
+/**
+ * 이 스펙을 빌더로 열었다가 저장하면 무엇이 달라지는가.
+ *
+ * 실측 스펙 85개 중 84개는 완전히 왕복한다(확인함). 남은 하나는 `_nav` — 페이지가
+ * 아니라 내비게이션 **배열**이라 빌더가 통째로 못 연다. 그런 스펙에 빌더를 열어 주면
+ * 저장 한 번에 내용이 사라진다. 경고만 띄우고 열어 두는 쪽이 친절해 보이지만, 이
+ * 편집기는 운영 정본을 직접 고치는 자리라 "실수로 저장"이 가장 비싼 사고다.
+ * **못 여는 스펙은 열지 않고 JSON으로 보낸다.**
+ */
+declare function builderFidelity(spec: unknown): BuilderFidelity;
+interface BuilderViewProps {
+    /** 편집할 스펙. **마운트와 `syncKey` 변경 때만** 읽는다(파일 머리말 참고). */
+    readonly spec: unknown;
+    /** 값이 바뀌면 문서를 `spec`으로 다시 채운다. 바깥이 내용을 갈아끼웠을 때만 올린다. */
+    readonly syncKey?: number | string;
+    /** 편집이 일어날 때마다 새 스펙. 안 바뀐 가지는 이전 호출과 같은 객체다. */
+    readonly onSpecChange: (spec: SduiPage) => void;
+    /** 고급(JSON) 모드로 넘긴다. 이유가 있으면 함께 준다. */
+    readonly onOpenJson?: (reason?: string) => void;
+    /** ⌘S. 주지 않으면 가로채지 않는다(브라우저 기본 동작이 그대로 산다). */
+    readonly onSave?: () => void;
+    /** `navigate` 액션 자동완성에 쓸 다른 페이지 id들 — `SpecStore.list()`의 결과. */
+    readonly pageIds?: readonly string[];
+    /**
+     * 캔버스가 그릴 때 쓸 레지스트리. 생략하면 {@link editorRegistry}(라이브러리 어휘
+     * 66종 + 렌더러 내장 `ForEach`)다. 소비 앱이 자기 컴포넌트를 얹었다면 **그 레지스트리를
+     * 그대로 넘겨야** 캔버스에 앱과 같은 그림이 나온다 — 안 넘기면 앱 고유 이름
+     * (`ExcelUploadCard` 등)이 "등록되지 않은 컴포넌트" 자리 표시가 된다(선택·이동은 된다).
+     */
+    readonly registry?: SduiRegistry;
+    /** 팔레트·속성 패널이 볼 메타데이터. 소비 앱 것을 합쳐 넘기면 그쪽도 나온다. */
+    readonly catalog?: Record<string, SduiComponentMeta>;
+    readonly can?: SduiCanSetting;
+    readonly className?: string;
+}
+declare function BuilderView({ spec, syncKey, onSpecChange, onOpenJson, onSave, pageIds, registry, catalog, can, className, }: BuilderViewProps): React__default.JSX.Element;
+
+/**
+ * 편집 화면이 레지스트리를 못 받았을 때 쓰는 **기본 어휘** — 그리고 그것 하나뿐이다.
+ *
+ * ## 왜 별도 모듈인가 (BuilderView.tsx에서 떼어 냈다)
+ *
+ * 기본값을 정하는 자리가 넷이었다 — `SduiEditor`·`EditorView`·`BuilderView`는 66종을
+ * 쓰는데 `Canvas`만 39종으로 떨어졌다. 원인은 값이 **`BuilderView.tsx` 안에** 살았다는
+ * 것이다. `Canvas`는 `BuilderView`의 **자식**이라 그걸 import하면 순환이 생긴다:
+ *
+ *     BuilderView.tsx → Canvas.tsx → BuilderView.tsx
+ *
+ * 그래서 캔버스만 이 값에 손이 닿지 않았고, 자기 셸을 짜서 `Canvas`를 단독 마운트한
+ * 소비자는 팔레트가 내건 것의 43%가 "등록되지 않은 컴포넌트"로 나오는 화면을 봤다.
+ * `ViewerView`도 같은 이유로 같은 구멍이 있었다(`SduiEditor`가 셸에서 때워 두었을 뿐,
+ * 단독 export라 단독 마운트에는 안 닿았다).
+ *
+ * 값을 **잎 모듈**로 내리면 그 순환이 구조적으로 불가능해진다. 그래서 이 파일은
+ * **지역 import가 0개**다(`@wipco/sdui`와 `react`만 본다). 그게 이 파일의 설계
+ * 제약이고, 여기에 `./model.js` 하나를 들이는 순간 위 순환이 되살아난다 —
+ * 편의를 위해서라도 넣지 말 것.
+ *
+ * `Canvas.tsx`에 두는 안도 검토했다가 버렸다. 소비 지점이 캔버스 **아래**(edit-runtime)와
+ * 캔버스 **옆**(SduiEditor·EditorView)으로 갈려 있어서, 거기 두면 셸이 어휘를 캔버스에서
+ * 꺼내 오는 모양이 된다 — 어휘 정의가 캔버스 구현에 딸린 것처럼 읽힌다.
+ *
+ * ## 왜 `defaultRegistry`로는 모자라나
+ *
+ * 팔레트는 메타데이터(`@wipco/sdui/meta`)가 아는 어휘 **69종**을 내건다(`hidden`인
+ * `Toast`만 빠져 화면에는 68종). 그런데
+ * `defaultRegistry`는 39종(+ 렌더러 내장 `ForEach`)뿐이라, 드롭인 사용자는 팔레트에서
+ * 집을 수 있는 것의 42%를 집어 **아무것도 그려지지 않는 페이지**를 만들 수 있었다.
+ * 팔레트에 있는데 안 그려지는 것은 빌더의 전제를 깨는 종류의 어긋남이라 기본을 넓힌다.
+ *
+ * 39 + DS 6 + 표시 위젯 21 = **66종**이고, `defaultRegistry`를 통째로 품는다
+ * (`test/registry-default.test.ts`가 포함 관계를 실제로 센다).
+ *
+ * ## 넓히되 코드 분할은 깨지 않는다
+ *
+ * 위젯 21종을 `defaultRegistry`처럼 정적으로 물면 그 21종이 편집기를 쓰는 모든 소비자의
+ * 초기 청크에 붙는다(측정치 77.4kB — 아래 청크 합). 0.3.0에서 위젯별 진입점을 만든 이유가
+ * 정확히 그것을 막기 위해서였고, 묶음(`@wipco/sdui/widgets`)을 한 번이라도 정적으로 물면
+ * 개별 진입점의 `lazy`까지 도로 합쳐진다(widgets/index.ts 주석 참고).
+ *
+ * 그래서 **위젯은 전부 개별 진입점 + 동적 import**다. 편집기 번들에는 `import()` 호출만
+ * 남고, 실제 코드는 그 위젯이 캔버스에 처음 그려질 때 청크로 내려온다.
+ * DS 6종은 반대로 정적이다 — core(`@wipco/sdui`)에 이미 있어 개별 진입점이 없고,
+ * 동적으로 불러 봐야 core 청크는 어차피 초기에 내려오므로 갈라지지 않는다.
+ *
+ * **재봤다**(apps/demo · vite build, 이 레지스트리를 넣기 전후를 같은 트리에서 비교):
+ * 초기 청크 1,047.22kB → 1,056.16kB로 **+8.94kB**(gzip +3.06kB). 그중 DS 6종이 2.33kB,
+ * 나머지 6.61kB가 `import()` 21개와 배선이다. 위젯 본체는 21개 청크로 갈라져 나갔다 —
+ * EventCalendar 13.47kB · OrgChart 6.00kB · ColumnBoard 5.92kB … Strip 0.98kB
+ * (21개 합 77.4kB, 방금 다시 셌다). 정적으로 물었다면 그게 초기 청크에 통째로 더해졌을 자리다.
+ *
+ * 이 모듈로 값을 옮기고 `Canvas`·`ViewerView`의 기본값으로 삼은 변경은 **초기 청크를
+ * 사실상 움직이지 않았다** — 1,062.16kB → 1,062.15kB(−0.01kB, gzip 328.70 → 328.46kB).
+ * 위젯 21개 청크는 크기가 하나도 안 변했다(해시만 바뀐다). 당연한 결과다 — 옮긴 것은
+ * 정의 위치일 뿐이고, 캔버스는 이미 `BuilderView` 경유로 이 값을 보고 있었다.
+ * **기본값을 넓히는 것과 번들이 커지는 것은 별개**라는 게 이 수치의 요점이다.
+ *
+ * (절대값은 라이브러리가 자라면 같이 움직인다. 이 파일을 고칠 때 확인할 것은 그 수가
+ *  아니라 **청크 목록에 위젯 이름이 그대로 남아 있는가**다 — 하나라도 초기 청크로
+ *  합쳐졌다면 정적 경로가 어디선가 생긴 것이다.)
+ *
+ * ## 여기 없는 것 — `Chart`·`MapPreview`
+ *
+ * 메타데이터 69종에서 이 둘과 `ForEach`를 빼면 66이다. **69가 아닌 이유가 그 셋이고,
+ * 셋 다 이유가 다르다.** `ForEach`는 렌더러 내장이라 레지스트리를 애초에 안 거친다.
+ * 나머지 둘은 이렇다.
+ *
+ * 그 둘은 `@wipco/sdui/rich`에 있고 recharts·ol이 **optional peerDependency**다
+ * (`packages/sdui/package.json`의 `peerDependenciesMeta`). 기본값이 그 진입점을 물면
+ * 두 라이브러리가 모든 편집기 소비자의 의존성 해석 대상이 되어, "선택 의존성"이라는
+ * 성질 자체가 없어진다 — 안 깔린 프로젝트는 위젯이 안내 플레이스홀더로 떨어지는 게
+ * 아니라 **빌드가 막힌다**(번들러가 `import('recharts')`를 해석하지 못한다).
+ *
+ * 넣어 보면 apps/demo는 멀쩡히 빌드된다(초기 청크 +0.70kB, recharts·ol은 따로 갈린다).
+ * **그걸 근거로 삼으면 안 된다** — demo는 워크스페이스 심볼릭 링크라 번들러가
+ * `packages/sdui/node_modules`에서 둘을 찾아낸다. 진짜 소비자에게는 그 경로가 없다.
+ *
+ * 두 이름은 소비자가 `registry` 프롭으로 얹고(`richComponents`가 그 스위치다),
+ * 얹지 않으면 팔레트가 "등록되지 않음"으로 표시한다. **이 2종이 팔레트와 캔버스 사이에
+ * 남는 유일한 격차이고, 그건 메우는 게 아니라 의도한 것이다.**
+ *
+ * ## `AutocompleteField`는 넣는다
+ *
+ * 라이브러리의 `widgetComponents` 묶음은 이 이름을 일부러 뺐다 — 조회(`endpoint`)가
+ * 앱 어댑터 주입을 받는데, 얹어 두면 그 스펙이 조용히 로컬 필터링으로 강등되기 때문이다.
+ * **편집 화면에는 그 위험이 없다.** 캔버스도 미리보기도 어댑터의 fetch를 막아 두어
+ * 조회가 애초에 일어나지 않는다. 여기서 뺐을 때 남는 것은 "조용한 강등"이 아니라
+ * 자리 표시뿐이고, 그건 자동완성 필드가 어떻게 생겼는지조차 못 보게 한다.
+ */
+
+/**
+ * 편집 화면(캔버스·미리보기·뷰어)의 기본 어휘 66종.
+ *
+ * 기본값을 정하는 자리는 이 값 **하나**다. 파일 머리말의 순환 문제 때문에 값이
+ * `BuilderView.tsx`에 갇혀 있던 동안 `Canvas`와 `ViewerView`가 각자 39종으로 떨어졌고,
+ * 그 어긋남을 화면에서 설명하는 것이 아무 데도 없었다. 새 기본값이 필요하면
+ * 여기서만 바꾸고, 새 화면을 만들면 여기서 가져다 쓴다.
+ */
+declare const editorRegistry: SduiRegistry;
+
+interface CanvasProps {
+    /** 소비 앱 어휘를 합친 카탈로그. 안 넘기면 라이브러리 어휘만 안다. */
+    catalog?: SduiCatalog;
+    doc: BuilderDoc;
+    selection: Selection;
+    hover: NodeId | null;
+    /** `editorReducer`의 dispatch. 캔버스는 변형 결과를 `apply`로만 넘긴다. */
+    dispatch: (action: EditorAction) => void;
+    /**
+     * 소비 앱이 자기 컴포넌트를 얹은 레지스트리.
+     *
+     * 생략하면 {@link editorRegistry} — 라이브러리 어휘 **66종**(렌더러 기본 39 + DS 6 +
+     * 표시 위젯 21, 여기에 렌더러 내장 `ForEach`)이다. 팔레트가 내거는 68종 중 여기 없는
+     * 것은 `Chart`·`MapPreview` 둘뿐이고, 그건 recharts·ol이 **optional peerDependency**라
+     * 일부러 뺀 것이다(editor-registry.tsx 주석). 소비자가 그 둘을 쓰려면 직접 얹어야 한다.
+     *
+     * 어휘 밖 컴포넌트(ExcelUploadCard 등)를 쓰는 스펙을 편집하려면 반드시 넘겨야 한다 —
+     * 안 넘기면 그 노드는 "등록되지 않은 컴포넌트" 자리 표시로 그려진다(선택·이동은 된다).
+     * 넓힐 때는 `createRegistry({ ...editorRegistry, ...myComponents })`로 **얹어야** 한다.
+     * `createRegistry(myComponents)`는 바탕이 `defaultRegistry` 39종이라 위젯 27종이 빠진다.
+     */
+    registry?: SduiRegistry;
+    /** `Can`의 판정. 캔버스는 게이트를 열어 두므로 보통 넘길 일이 없다. */
+    can?: SduiCanSetting;
+    className?: string;
+}
+declare function Canvas({ doc, catalog, selection, hover, dispatch, 
+/**
+ * 기본값이 여기 붙어 있는 이유 — 이 자리가 비면 한 단계 아래
+ * `createEditRegistry(base = defaultRegistry)`가 받아 **39종**으로 떨어진다.
+ * `BuilderView`로 열면 셸이 66종을 내려 주지만, 자기 셸을 짜서 `Canvas`를 단독으로
+ * 마운트한 소비자에게는 그 셸이 없다. 그러면 팔레트가 `Timeline`을 멀쩡히 내걸고
+ * 캔버스는 "등록되지 않은 컴포넌트: Timeline"이라 답하는데, 왜 다른지 설명하는 것이
+ * 화면 어디에도 없다 — 소비자는 "라이브러리에 없구나"로 오귀인한다.
+ */
+registry, can, className, }: CanvasProps): React.JSX.Element;
+
+interface PaletteProps {
+    doc: BuilderDoc;
+    selection: Selection;
+    dispatch: (action: EditorAction) => void;
+    /**
+     * 팔레트에 띄울 메타데이터. 생략하면 라이브러리 어휘 69종(`allComponentMeta`).
+     * 소비 앱이 얹은 컴포넌트도 팔레트에 내려면 그 메타데이터를 합쳐 넘긴다.
+     */
+    catalog?: Record<string, SduiComponentMeta>;
+    /**
+     * 캔버스가 실제로 그릴 때 쓰는 레지스트리 — **표시 전용**이다(팔레트는 아무것도 렌더하지
+     * 않는다). 여기 없는 이름을 "등록되지 않음"으로 밝히는 근거로만 쓴다.
+     *
+     * 생략하면 아무 표시도 하지 않는다. 무엇이 그려질지 모르는 채로 경고를 붙이면
+     * 멀쩡한 조각에 거짓 경고가 달리는데, 그건 표시가 없는 것보다 나쁘다.
+     * 셸(`BuilderView`)은 캔버스에 넘기는 것과 **같은 값**을 여기에도 넘긴다.
+     */
+    registry?: SduiRegistry;
+    className?: string;
+}
+declare function Palette({ doc, selection, dispatch, catalog, registry, className }: PaletteProps): React.JSX.Element;
+
+/**
+ * 편집 한 번. `dispatch({ type: 'apply', ...change })`에 그대로 넣을 수 있는 모양이다.
+ */
+interface InspectorChange {
+    readonly result: TransformResult;
+    /** 실행취소 메뉴에 나갈 한국어 이름 */
+    readonly label: string;
+    /** 연속 입력을 한 칸으로 합칠 키. 없으면 항상 새 칸. */
+    readonly coalesce?: string;
+    /**
+     * 속성 편집은 **선택을 건드리지 않는다**. 리듀서의 기본값(`affected`)을 그냥 두면
+     * 여러 노드를 골라 둔 상태에서 프롭 하나만 고쳐도 선택이 기준 노드 하나로 줄어든다.
+     */
+    readonly select: 'keep';
+}
+interface InspectorProps {
+    /** 소비 앱 어휘를 합친 카탈로그. 안 넘기면 라이브러리 어휘만 안다. */
+    readonly catalog?: SduiCatalog;
+    readonly doc: BuilderDoc;
+    readonly selection: Selection;
+    readonly onApply: (change: InspectorChange) => void;
+    /**
+     * 바인딩 편집기 위임 — 다른 담당이 만든다.
+     *
+     * 주지 않으면 바인딩 값은 JSON으로 편집할 수 있는 상태로 남는다(값을 못 고치게
+     * 막지는 않는다). 인자는 프롭 이름 하나이고, 대상 노드는 `selection.primary`다.
+     */
+    readonly onRequestBinding?: (propName: string) => void;
+    /** 노드의 React `key`까지 편집할 수 있게 한다. 기본 true. */
+    readonly allowKeyEdit?: boolean;
+    readonly className?: string;
+}
+declare function Inspector({ doc, catalog, selection, onApply, onRequestBinding, allowKeyEdit, className, }: InspectorProps): React.JSX.Element;
+
+/**
+ * 편집 문서에서 **화면이 필요로 하는 것들을 뽑아내는** 파생 조회.
+ *
+ * 문서를 바꾸지 않는다(전부 읽기 전용). 트리 패널·속성 패널·바인딩 자동완성이
+ * 여기서 같은 답을 가져가야 세 화면이 서로 다른 말을 하지 않는다.
+ *
+ * 결과를 캐시하지 않는 이유는 문서가 불변이라서다 — 호출부가
+ * `useMemo(() => flattenTree(doc), [doc])`로 감싸면 그게 곧 정확한 캐시다.
+ * 여기서 WeakMap을 하나 더 두면 무효화 규칙만 두 벌이 된다.
+ */
+
+interface ChildLabel {
+    /** 한국어 표시명. 메타데이터가 없으면 컴포넌트 이름 그대로. */
+    readonly label: string;
+    /** 무엇이 들어 있는지 한 줄 힌트. 없을 수 있다. */
+    readonly hint?: string;
+    /** 팔레트 아이콘 이름(`ICON_NODES` 기준). 메타데이터가 없으면 undefined. */
+    readonly icon?: string;
+    /** 메타데이터를 아는 어휘인가. false면 소비 앱이 레지스트리에 얹은 컴포넌트다. */
+    readonly known: boolean;
+}
+/** 트리·브레드크럼·선택 배지가 함께 쓰는 표시 이름. */
+declare function describeChild(child: BuilderChild, catalog?: SduiCatalog): ChildLabel;
+/** 선택된 노드가 어디에 있는지 — 바깥에서 안쪽 순서. 마지막 항목이 자기 자신이다. */
+declare function breadcrumbOf(doc: BuilderDoc, id: NodeId, catalog?: SduiCatalog): ReadonlyArray<{
+    id: NodeId;
+    label: string;
+}>;
+interface SlotDescriptor {
+    readonly slot: string;
+    /** 한국어 표시명. 기본 슬롯은 메타데이터의 `children.label`이 있으면 그걸 쓴다. */
+    readonly label: string;
+    readonly description?: string;
+    readonly count: number;
+    /** 메타데이터가 아는 슬롯인가. false면 스펙에만 있는 슬롯 — 지우지 말고 그대로 보여 준다. */
+    readonly known: boolean;
+    /** 여기에 무언가 놓을 수 있는가. */
+    readonly accepts: boolean;
+    /** 실측 스펙에서 이 슬롯이 쓰인 총 횟수 — 많이 쓰는 자리를 위로 올린다. */
+    readonly seen: number;
+}
+/**
+ * 이 노드가 가진 드롭 자리 전부.
+ *
+ * **비어 있는 슬롯도 돌려준다.** 실측에서 `Dialog.footer`는 227회 쓰이는 최다 슬롯인데,
+ * 지금 비어 있다는 이유로 목록에서 빼면 사용자가 그 자리를 찾을 방법이 없다.
+ * 반대로 메타데이터가 모르는 슬롯이 스펙에 있으면 그것도 함께 돌려준다 —
+ * 편집기가 모르는 자리를 감추면 그 안의 내용은 편집도 삭제도 못 하는 유령이 된다.
+ *
+ * 정렬은 기본 슬롯 → 실측 빈도 순이다.
+ */
+declare function slotsOf(node: BuilderNode, catalog?: SduiCatalog): readonly SlotDescriptor[];
+type TreeRowKind = 'node' | 'text' | 'slot';
+interface TreeRow {
+    readonly kind: TreeRowKind;
+    /** 행 고유 키. 노드/텍스트는 id, 슬롯 행은 `부모id#슬롯`. 펼침 상태의 키이기도 하다. */
+    readonly key: string;
+    /** 슬롯 행이면 null. */
+    readonly id: NodeId | null;
+    readonly depth: number;
+    /** 이 행이 놓인 자리. 슬롯 행은 index가 -1이다. */
+    readonly parent: NodeId;
+    readonly slot: string;
+    readonly index: number;
+    readonly label: string;
+    readonly hint?: string;
+    readonly icon?: string;
+    readonly component?: string;
+    /** 펼칠 것이 있는가. */
+    readonly expandable: boolean;
+    /**
+     * 화면에 자기 모습이 없는 논리 래퍼(Show·Can·ForEach)인가.
+     * 실측에서 `body` 직속 최상위의 1위가 `Show`(153회)라, 트리에서 이걸 구분해 주지 않으면
+     * "아무것도 없는 페이지"처럼 보인다.
+     */
+    readonly logical: boolean;
+    /** 메타데이터를 아는 어휘인가. */
+    readonly known: boolean;
+}
+interface FlattenOptions {
+    /**
+     * 펼쳐진 행의 키 집합. 생략하면 전부 펼친다.
+     * 슬롯 행을 접으면 그 안의 자식도 나오지 않는다.
+     */
+    readonly expanded?: ReadonlySet<string>;
+    /**
+     * 슬롯 행을 낼 것인가. 기본 true —
+     * 슬롯이 1급 드롭 타깃이라 트리에도 자리가 있어야 한다.
+     * 자식이 기본 슬롯에만 있는 노드는 슬롯 행을 생략해 트리를 얕게 유지한다.
+     */
+    readonly showSlots?: boolean;
+    /** 소비 앱 어휘를 합친 카탈로그. 안 넘기면 앱 고유 컴포넌트가 이름 그대로 나온다. */
+    readonly catalog?: SduiCatalog;
+}
+/**
+ * 트리 패널이 그릴 평평한 행 목록. 가상 스크롤을 붙이기 쉽도록 중첩 대신 `depth`를 준다.
+ */
+declare function flattenTree(doc: BuilderDoc, options?: FlattenOptions): readonly TreeRow[];
+/**
+ * 이 노드 근처에서 실제로 놓을 수 있는 자리들 — 캔버스가 드래그 중 후보를 띄울 때 쓴다.
+ * 대상 컴포넌트 이름(문자열 자식이면 model의 `TEXT_CHILD`)을 주면 막히는 자리는 빼고 돌려준다.
+ */
+declare function dropTargetsAround(doc: BuilderDoc, hoveredId: NodeId, child: string, catalog?: SduiCatalog): ReadonlyArray<{
+    target: DropTarget;
+    label: string;
+    recommended: boolean;
+}>;
+/**
+ * 키가 어디서 왔는가.
+ *
+ * - `form`       Form의 initial/rules/labels/initialFromUrl에 이름이 있는 필드
+ * - `formSystem` 렌더러가 직접 쓰는 `{폼id}.$errors` · `$submitting` · `$dirty`
+ * - `setState`   setState/open/close/array* 액션이 쓰는 키
+ * - `default`    `{ "$state": k, "default": ... }` — 기본값을 준 참조는 선언에 준한다
+ * - `urlState`   페이지의 `urlState` 목록
+ * - `read`       읽히기만 하는 키
+ */
+type StateKeyOrigin = 'form' | 'formSystem' | 'setState' | 'default' | 'urlState' | 'read';
+interface StateKeyEntry {
+    readonly key: string;
+    readonly origins: readonly StateKeyOrigin[];
+    /** `read` 말고 다른 출처가 하나라도 있는가. */
+    readonly declared: boolean;
+    readonly reads: number;
+    readonly writes: number;
+    /** 이 키를 언급하는 노드들 — 트리에서 "이 키를 쓰는 곳으로" 이동하는 데 쓴다. */
+    readonly nodes: readonly NodeId[];
+}
+interface StateKeyNode {
+    readonly segment: string;
+    /** 루트부터의 전체 키. */
+    readonly key: string;
+    /** 이 경로 자체가 문서에 등장했으면 그 항목. 중간 마디는 없을 수 있다. */
+    readonly entry?: StateKeyEntry;
+    /**
+     * 조상 중에 선언된 키가 있는가.
+     *
+     * **`selectedClient`를 setState로 넣고 `selectedClient.address`를 읽는 것은 정상이다.**
+     * 하위 필드는 API 응답 모양에서 오지 스펙에 있지 않다 — 스펙만 봐서는 알 수 없다.
+     * 이 플래그가 true인 키는 절대 오류로 표시하면 안 된다.
+     */
+    readonly derived: boolean;
+    readonly children: readonly StateKeyNode[];
+}
+interface StateKeyIndex {
+    readonly entries: ReadonlyMap<string, StateKeyEntry>;
+    /** 점(`.`)으로 쪼갠 계층 트리. 자동완성 드롭다운이 그대로 그린다. */
+    readonly tree: readonly StateKeyNode[];
+    /** 문서에 있는 Form들 — submitForm 편집기와 폼 필드 자동완성이 쓴다. */
+    readonly forms: ReadonlyMap<string, {
+        readonly node: NodeId;
+        readonly fields: readonly string[];
+    }>;
+}
+/**
+ * 문서를 훑어 `$state` 키를 모은다.
+ *
+ * 실측에서 바인딩 1,464회 중 `$state`가 1,100회(75%)고 서로 다른 키가 **786개**다.
+ * 이 정도면 자유 입력으로는 오타가 반드시 나고, 오타 난 키는 예외 없이
+ * "화면에 아무것도 안 나옴"으로만 드러난다(렌더러는 없는 키를 `default`로 조용히 대체한다).
+ * 그래서 자동완성이 선택이 아니라 필수다.
+ */
+declare function buildStateKeyIndex(doc: BuilderDoc): StateKeyIndex;
+/**
+ * 키 하나의 상태.
+ *
+ * - `declared` 문서 어딘가가 이 키를 만든다(setState·Form·urlState·default)
+ * - `derived`  조상 키가 선언돼 있고 이건 그 하위 필드다 — **정상이다**
+ * - `read`     읽히기만 한다. 다른 페이지나 앱 코드가 넣어 줄 수도 있다
+ * - `unknown`  문서 어디에도 없다
+ *
+ * 넷 중 무엇도 **오류가 아니다.** `unknown`조차 "혹시 오타인가요?" 수준의 귀띔이 상한선이다 —
+ * 상태를 채우는 주체가 스펙 밖(호스트 앱·API 응답)에 있는 것이 이 계약의 정상 동작이다.
+ */
+declare function stateKeyStatus(index: StateKeyIndex, key: string): 'declared' | 'derived' | 'read' | 'unknown';
+/**
+ * 자동완성 후보. 선언된 키를 먼저, 그다음 많이 쓰인 순으로 준다.
+ * `query`가 비면 전체를 같은 순서로 준다.
+ */
+declare function suggestStateKeys(index: StateKeyIndex, query?: string, limit?: number): readonly StateKeyEntry[];
+
+/**
+ * 트리의 드래그 앤 드롭 규약과 **놓을 자리 계산**.
+ *
+ * 편집기 안에서 오가는 드래그(팔레트→트리, 트리→캔버스)는 세 패널이 함께 보는
+ * 모듈 보관소(`../canvas/dnd.js`)를 통한다 — `./bridge.js`가 그 다리다.
+ * 여기 있는 MIME 규약은 **바깥에서 들어오는 드래그의 폴백**이다: 다른 창이나 아직
+ * 공용 보관소를 모르는 도구가 스펙 조각을 떨궈도 트리가 받아 낼 수 있게 한다.
+ *
+ * ## 왜 payload를 모듈 변수에도 들고 있는가
+ *
+ * HTML5 드래그는 `dragover` 동안 `dataTransfer.getData()`를 **빈 문자열로 막는다**
+ * (보호 모드 — 드롭하기 전에는 내용을 못 읽는다). 읽을 수 있는 것은 `types` 목록뿐이다.
+ * 그런데 트리는 끌고 오는 동안 "여기 놓아도 되는가"를 색으로 답해야 하고, 그 판정에는
+ * 컴포넌트 이름이 필요하다. 그래서 드래그를 **시작한 쪽이** {@link publishDrag}로
+ * 같은 문서 안의 모듈 변수에 payload를 남기고, 받는 쪽은 그것을 읽어 미리 판정한다.
+ * (같은 번들 안에서만 통한다. 다른 창이나 바깥 앱에서 온 드래그는 `types`만 보고
+ *  낙관적으로 받아 준 뒤 `drop`에서 실제 내용으로 다시 판정한다 — 이때는 거절 사유를
+ *  화면에 남긴다.)
+ *
+ * ## MIME
+ *
+ * 팔레트·캔버스와 나눠 쓰는 이름이라 상수로 고정한다. 팔레트가 다른 형식을 쓰면
+ * 트리에 `readDrag`를 갈아 끼우는 대신 `TreeView`의 `readDrag` 프롭으로 넘기면 된다.
+ *
+ * - `application/x-sdui-nodes`     문서 안 노드 이동 — id 배열
+ * - `application/x-sdui-spec`      새 조각 삽입 — `SduiChild` 또는 그 배열
+ * - `application/x-sdui-component` 새 조각 삽입 — 컴포넌트 이름만(메타데이터 기본 조각을 쓴다)
+ */
+
+/** 문서 안의 노드를 옮기는 드래그. */
+interface MoveDrag {
+    readonly kind: 'move';
+    readonly ids: readonly NodeId[];
+    /** 드롭 판정에 쓰는 이름들(문자열 자식은 {@link TEXT_CHILD}). */
+    readonly components: readonly string[];
+}
+/** 새 조각을 넣는 드래그(팔레트·붙여넣기). */
+interface InsertDrag {
+    readonly kind: 'insert';
+    readonly specs: readonly SduiChild[];
+    readonly components: readonly string[];
+}
+type TreeDrag = MoveDrag | InsertDrag;
+
+/**
+ * 트리 패널 — 페이지 구조를 계층으로 보여 주고, 거기서 바로 고른다·옮긴다.
+ *
+ * ## 왜 트리가 선택 사항이 아닌가 (실측)
+ *
+ * - 중첩이 **최대 14단계**다. 캔버스에서 그 깊이의 노드를 정확히 집는 것은 사실상 불가능하다.
+ * - `body` 직속 최상위 1위가 **`Show` 153회**고 그 안이 `Dialog` 129회다. 논리 래퍼와
+ *   닫힌 다이얼로그는 **캔버스에 아무 모습도 남기지 않는다** — 트리가 없으면 그 노드들은
+ *   편집기에서 존재하지 않는 것과 같다.
+ * - 슬롯은 캔버스에서 부모와 겹쳐 보인다. `Dialog.footer`는 실측 최다 슬롯(227회)인데
+ *   비어 있을 때는 캔버스에 클릭할 픽셀조차 없다. 그래서 여기서는 **슬롯이 별도 가지**이고,
+ *   비어 있어도 자리를 남긴다(`tree/rows.ts`).
+ *
+ * ## 상태를 여기서 들지 않는다
+ *
+ * 문서·선택·실행취소는 전부 `state.ts`의 리듀서가 든다. 이 컴포넌트가 스스로 가진 상태는
+ * **트리에만 있는 것**뿐이다 — 펼침 집합, 검색어, 드래그 중 미리보기. 그래야 캔버스와
+ * 속성 패널이 같은 선택을 보고, 되돌리기가 트리 조작까지 한 칸으로 되돌린다.
+ */
+
+interface TreeViewProps {
+    /** 소비 앱 어휘를 합친 카탈로그. 안 넘기면 라이브러리 어휘만 안다. */
+    readonly catalog?: SduiCatalog;
+    readonly state: EditorState;
+    readonly dispatch: React__default.Dispatch<EditorAction>;
+    /**
+     * 바깥에서 온 드래그를 해석한다. 기본값은 `tree/dnd.js`의 규약(MIME 세 가지)이다.
+     * 팔레트가 다른 형식을 쓰면 여기에 해석기를 끼우면 된다.
+     */
+    readonly readDrag?: (dataTransfer: DataTransfer) => TreeDrag | null;
+    /** 행을 더블클릭했을 때 — 고급 모드(JSON)로 넘기는 등 바깥이 정한다. */
+    readonly onActivate?: (id: NodeId) => void;
+    readonly className?: string;
+}
+declare function TreeView({ state, catalog, dispatch, readDrag, onActivate, className, }: TreeViewProps): React__default.JSX.Element;
+
+/**
+ * 실행취소 바 — 되돌리기/다시하기 버튼과 단축키, 그리고 **무엇이 되돌려지는지**.
+ *
+ * 되돌리기의 단위는 `state.ts`가 정한다(같은 프롭 연속 타이핑은 700ms 창으로 한 칸,
+ * 드래그는 `txn begin/end`로 한 칸, 구조 변경은 절대 합치지 않는다). 여기서는 그 기록을
+ * **읽어서 보여 주기만** 한다 — 단위를 화면 쪽에서 한 번 더 정하면 두 규칙이 어긋난다.
+ *
+ * ## 왜 이름을 계속 띄우는가
+ *
+ * 시각 빌더에서 되돌리기는 "방금 뭘 했는지 기억나지 않을 때" 눌린다. 드래그 한 번이
+ * 어디까지 한 칸인지 화면에 없으면 사용자는 Ctrl+Z를 서너 번 연타해 필요한 것까지
+ * 지운다. 그래서 버튼 옆에 **다음에 되돌려질 것의 이름**을 상시로 두고, 누른 뒤에는
+ * 잠시 "무엇을 되돌렸는지"로 바꿔 준다. 여러 칸을 한 번에 되돌릴 수 있게 기록 목록도 낸다.
+ */
+
+interface HistoryBarProps {
+    readonly state: EditorState;
+    readonly dispatch: React__default.Dispatch<EditorAction>;
+    /** ⌘Z/⌘⇧Z(Ctrl+Z/Ctrl+Y)를 문서 전역에 걸 것인가. 기본 true. */
+    readonly shortcuts?: boolean;
+    /** 여러 칸을 한 번에 되돌리는 기록 목록 버튼. 기본 true. */
+    readonly menu?: boolean;
+    readonly className?: string;
+}
+/**
+ * 지금 글자를 치고 있는 자리인가.
+ *
+ * 입력·textarea·contenteditable, 그리고 **CodeMirror(고급 JSON 모드)** 안에서는
+ * ⌘Z를 가로채면 안 된다. 그 안에는 각자의 실행취소가 있고, 그것을 빼앗으면
+ * "한 글자 되돌리려다 방금 만든 카드가 사라지는" 일이 생긴다.
+ *
+ * **이 함수는 "여기가 입력인가"만 답한다 — "그래서 양보하는가"는 키마다 다르다.**
+ * 처음에는 이 판정 하나로 모든 단축키를 잘랐는데, 그건 ⌘Z에만 맞는 답이었다.
+ * ⌘S는 입력 안에 경쟁하는 뜻이 아예 없고, Escape는 뜻이 있어도 편집기 쪽 처리가
+ * 더 자연스럽다. 키별 판단은 그것을 거는 쪽(`BuilderView`)이 한다.
+ */
+declare function isTypingTarget(target: EventTarget | null): boolean;
+/**
+ * ⌘Z/⌘⇧Z(그리고 Ctrl+Y)를 창 전체에 건다.
+ * 트리·캔버스·속성 패널 어디에 초점이 있어도 같은 기록을 되돌리게 하려는 것이다.
+ */
+declare function useUndoRedoShortcuts(state: EditorState, dispatch: React__default.Dispatch<EditorAction>, enabled?: boolean): void;
+declare function HistoryBar({ state, dispatch, shortcuts, menu, className, }: HistoryBarProps): React__default.JSX.Element;
+
+/**
+ * 액션 필드의 **후보 목록**을 문서에서 캐낸다.
+ *
+ * 오타 하나가 조용히 아무 일도 안 일어나게 만드는 자리들이라
+ * (`close`가 없는 키를 닫아도 렌더러는 그냥 false를 쓴다) 자유 입력만 두면 안 된다.
+ * 다만 어느 목록도 **완전하지 않다** — 상태를 채우는 주체가 스펙 밖(호스트 앱)에 있는 것이
+ * 이 계약의 정상 동작이다. 그래서 전부 "고를 수도 있고 직접 칠 수도 있는" 목록으로 낸다.
+ */
+
+interface Candidate {
+    readonly value: string;
+    /** 목록에 보일 한국어 설명. 없으면 값만 보여 준다. */
+    readonly hint?: string;
+    /** 문서에서 근거를 찾은 값인가. false면 "다른 데서 온 값"이라 경고하지 않는다. */
+    readonly grounded: boolean;
+    readonly node?: NodeId;
+}
+/**
+ * 액션이 들어가는 프롭인가.
+ *
+ * 렌더러는 `on`으로 시작하는 프롭만 핸들러로 바꾸지만, `SearchResults.rowClick`처럼
+ * **컴포넌트가 자기 손으로 dispatch하는 프롭**이 실측에 있다(메타데이터는 `kind: 'action'`).
+ * 둘 다 액션 자리로 본다. 메타데이터를 모르는 컴포넌트는 이름 규칙만으로 판단한다.
+ */
+declare function looksLikeActionProp(component: string, prop: string, catalog?: SduiCatalog): boolean;
+
+/**
+ * `$item`/`$index`가 **의미를 갖는 자리인지** 판정한다.
+ *
+ * 렌더러는 ForEach의 기본 자식만 반복 스코프로 감싼다(`SduiRenderer`의 `rowScope`).
+ * 그 밖에서 `$item`을 쓰면 예외도 경고도 없이 `null`이 되고, 화면에는 빈칸만 남는다 —
+ * 실측 스펙 84개의 `$item`/`$index` 206회가 **예외 없이** ForEach 안이었던 것도
+ * 밖에서 쓴 것이 조용히 죽어 살아남지 못했기 때문이라고 봐야 한다.
+ * 그래서 스코프 밖에서는 선택지로 **제시하지 않는다**(이미 들어 있으면 감추지 않는다 —
+ * 감추면 고칠 수가 없다).
+ *
+ * 주의할 자리가 둘 있다.
+ *  - `ForEach.source` 자체는 바깥 스코프에서 풀린다. 그래서 ForEach **자기 프롭**은 스코프 밖이다.
+ *  - `ForEach#empty` 슬롯은 행이 없을 때 그리므로 행이 없다. 역시 스코프 밖이다.
+ */
+
+interface ForEachScope {
+    /** 감싼 ForEach 개수. 0이면 스코프 밖이다. */
+    readonly depth: number;
+    /** 가장 안쪽 ForEach — `$item`이 가리키는 행의 주인이다. */
+    readonly nearest: NodeId | null;
+    readonly inScope: boolean;
+    /** 스코프 밖일 때의 한국어 사유. 화면에 그대로 띄우면 된다. */
+    readonly reason?: string;
+    /** `$item`의 필드 후보 — 확정 목록이 아니라 귀띔이다(자유 입력을 막지 않는다). */
+    readonly fields: readonly string[];
+}
+
+/**
+ * 바인딩·액션 편집기가 자동완성에 쓰는 재료 묶음.
+ *
+ * **두 층으로 나눠 두었다.** 상태 키 인덱스와 후보 목록은 문서 전체를 훑는 일이라
+ * 문서가 바뀔 때만 다시 만들면 되고, ForEach 스코프 판정은 조상 사슬만 타는 일이라
+ * 선택이 바뀔 때마다 해도 싸다. 한 함수로 합치면 노드를 클릭할 때마다 786개짜리
+ * 키 인덱스를 다시 세우게 된다.
+ *
+ * ```ts
+ * const source = useMemo(() => createBindingSource(doc, pageIds), [doc, pageIds]);
+ * const ctx = useMemo(() => bindingContextFor(source, selection.primary), [source, selection.primary]);
+ * ```
+ */
+
+/** 문서에만 의존하는 재료. 문서가 바뀔 때만 다시 만든다. */
+interface BindingSource {
+    readonly doc: BuilderDoc;
+    readonly stateKeys: StateKeyIndex;
+    /** Dialog를 품은 Show의 게이트 키 — open/close 후보 */
+    readonly dialogKeys: readonly Candidate[];
+    /** navigate 후보 (스펙 id + 이 페이지가 이미 쓰는 경로) */
+    readonly pages: readonly Candidate[];
+    /** submitForm/download 엔드포인트 후보 */
+    readonly endpoints: readonly Candidate[];
+    /** 폼 id → 필드 목록 */
+    readonly forms: StateKeyIndex['forms'];
+}
+declare function createBindingSource(doc: BuilderDoc, pageIds?: readonly string[], catalog?: SduiCatalog): BindingSource;
+/** 편집 중인 노드까지 얹은 최종 컨텍스트. 선택이 바뀔 때마다 만들어도 싸다. */
+interface BindingContext extends BindingSource {
+    /** 값이 놓일 노드. null이면 `$item`/`$index`를 제시하지 않는다. */
+    readonly nodeId: NodeId | null;
+    readonly scope: ForEachScope;
+}
+declare function bindingContextFor(source: BindingSource, nodeId: NodeId | null): BindingContext;
+/** 한 번에 만들고 싶을 때(테스트·간단한 호출부). 위 두 단계를 그냥 붙인 것이다. */
+declare function createBindingContext(doc: BuilderDoc, nodeId: NodeId | null, pageIds?: readonly string[]): BindingContext;
+
+/**
+ * 값 하나를 편집한다 — **상수인가 바인딩인가**를 고르고, 바인딩이면 종류까지.
+ *
+ * 배치는 쉽고 바인딩이 어렵다. 여기서 대충 하면 사용자는 결국 JSON을 연다.
+ * 실측 84개에서 나온 세 가지 사실이 이 화면의 모양을 결정했다.
+ *
+ *  1. **바인딩 1,464회 중 `$state`가 1,100회(75%)**다. 종류 고르기는 한 번의 클릭이어야 하고,
+ *     상태 키 칸은 처음부터 자동완성이 붙어 있어야 한다(→ `StateKeyPicker`).
+ *  2. **`$item`/`$index` 206회가 전부 ForEach 안**이었다. 밖에서 쓰면 조용히 null이 되므로
+ *     스코프 밖에서는 아예 제시하지 않는다. 다만 **이미 들어 있으면 감추지 않는다** —
+ *     감추면 잘못 들어간 값을 고칠 방법이 사라진다.
+ *  3. **`$calc`는 인자가 다시 바인딩**이라 최대 3단까지 중첩됐다. 재귀 편집이 필수고,
+ *     깊어지면 폼만 봐서는 못 읽으므로 한 줄 수식 미리보기를 항상 띄운다.
+ *
+ * 종류를 바꿔도 값을 잃지 않는다(`ValueStash`). 왕복해서 원래 값이 안 돌아오면
+ * 사용자는 전환 자체를 피하게 되고, 그럼 이 편집기는 없는 것과 같다.
+ */
+
+interface BindingEditorProps {
+    value: SduiPropValue | undefined;
+    onChange: (value: SduiPropValue | undefined) => void;
+    /** 자동완성 재료. `createBindingSource`/`bindingContextFor`로 만든다. */
+    ctx: BindingContext;
+    /** 프롭 정의 — 상수 입력의 모양과 `bindable` 권고를 여기서 읽는다. */
+    meta?: SduiPropMeta | undefined;
+    autoFocus?: boolean;
+    /** 재귀 깊이(내부용). 너무 깊어지면 JSON으로 안내한다. */
+    depth?: number;
+    /** 바인딩을 받을 수 없는 자리(예: `$state`의 default)에서 종류 선택을 감춘다. */
+    literalOnly?: boolean;
+    'aria-label'?: string;
+}
+declare function BindingEditor({ value, onChange, ctx, meta, autoFocus, depth, literalOnly, 'aria-label': ariaLabel, }: BindingEditorProps): React__default.JSX.Element;
+
+/**
+ * `on*` 프롭에 붙는 **액션 목록**을 편집한다.
+ *
+ * 실측 1,685회 중 `setState` 636 · `close` 390 · `open` 175로 이 셋이 66%다. 그래서
+ * 빠른 추가 버튼을 이 셋으로 두고 목록도 빈도순으로 정렬했다. 그러나 나머지 어휘도
+ * **전부 편집 가능하다** — 어휘를 좁히면 그걸 쓰는 기존 페이지를 이 편집기로 못 연다.
+ *
+ * 세 가지를 특히 조심했다.
+ *
+ *  1. **모양 보존.** 실측 액션 프롭 1,140개 중 930개가 배열이 아니라 객체 하나다.
+ *     하나로 남는 한 객체로 되돌려 쓴다(→ `writeActionList`). 안 그러면 한 글자도 안 고친
+ *     페이지를 열고 저장하는 것만으로 930군데가 바뀐 diff가 나온다.
+ *  2. **어휘 밖 액션·모르는 필드 보존.** 스키마에 없으면 원시 JSON으로 떨어뜨리되
+ *     절대 버리지 않는다. 편집기가 모르는 값을 지우는 것이 이 도구의 최악의 오작동이다.
+ *  3. **순서.** 한 프롭에 액션이 18개까지 붙는다(실측 최대). 접힌 목록 + 위/아래가 기본이다.
+ */
+
+interface ActionEditorProps {
+    value: SduiPropValue | undefined;
+    onChange: (value: SduiPropValue | undefined) => void;
+    ctx: BindingContext;
+    /** 프롭 정의 — `eventArg`(핸들러에 들어오는 값) 설명을 여기서 읽는다. */
+    meta?: SduiPropMeta | undefined;
+    depth?: number;
+    'aria-label'?: string;
+}
+declare function ActionEditor({ value, onChange, ctx, meta, depth, 'aria-label': ariaLabel, }: ActionEditorProps): React__default.JSX.Element;
+
+/**
+ * 액션 어휘의 **편집 스키마** — 어떤 필드를 어떤 입력으로 그릴지.
+ *
+ * 실측 1,685회 중 `setState` 636 · `close` 390 · `open` 175로 셋이 66%다. 그래서 이 셋은
+ * 1급으로 올리되(빈도순 정렬 + 빠른 추가), **나머지도 전부 편집 가능해야 한다** —
+ * 어휘를 좁히면 그걸 쓰는 기존 페이지를 편집기로 못 연다.
+ *
+ * 스키마에 없는 필드와 스키마에 없는 액션을 **버리지 않는 것**이 이 파일의 핵심 계약이다.
+ * 편집기가 모르는 값을 지우는 것이 이 도구가 낼 수 있는 최악의 오작동이다.
+ */
+
+type ActionValue = Readonly<Record<string, SduiPropValue>>;
+interface ActionList {
+    readonly actions: readonly ActionValue[];
+    /**
+     * 원래 스펙이 배열이 아니라 **객체 하나**였는가.
+     *
+     * 실측 액션 프롭 1,140개 중 930개가 객체 하나다. 편집기가 이걸 전부 배열로 펴면
+     * 한 글자도 안 고친 페이지를 열고 저장하는 것만으로 930군데가 바뀐 diff가 나온다.
+     * 그래서 개수가 하나로 남는 한 원래 모양을 지킨다.
+     */
+    readonly single: boolean;
+    /** 액션이 아닌 것이 섞여 있었는가 — 그대로 보존하되 화면에 알린다. */
+    readonly strays: readonly SduiPropValue[];
+}
+declare function readActionList(value: SduiPropValue | undefined): ActionList;
+/**
+ * 다시 스펙 값으로. 액션이 하나도 없으면 `undefined`를 돌려주고,
+ * 호출부는 그걸로 프롭 자체를 지운다(`setProp(doc, id, name, undefined)`).
+ */
+declare function writeActionList(list: ActionList): SduiPropValue | undefined;
+
+/**
+ * 값과 액션을 **한 줄로** 읽히게 만든다.
+ *
+ * `$calc`는 인자가 다시 바인딩일 수 있어서 실측 최대 3단까지 중첩된다
+ * (`concat(count($state:items), "개 품목")` 같은 것). 접힌 폼을 펼쳐 가며 읽는 것보다
+ * `개수({items}) ⧺ "개 품목"` 한 줄이 훨씬 빠르다 — 편집은 폼에서 하고, 확인은 이 줄로 한다.
+ */
+
+/**
+ * 값 하나를 수식처럼. 리터럴은 JSON에 가깝게, 바인딩은 중괄호 표기로 낸다.
+ * `depth`는 재귀 폭주 방지용이다(스펙은 신뢰할 수 없는 입력이라 순환을 배제하지 못한다).
+ */
+declare function formatValue(value: SduiPropValue | undefined, depth?: number): string;
+/**
+ * 액션 한 줄 요약. 접힌 목록에서 **무엇을 하는 액션인지**만 보이면 된다.
+ *
+ * 실측에서 한 프롭에 액션이 18개까지 붙는다. 그 목록을 전부 펼쳐 놓으면 화면이 죽으므로
+ * 접힌 상태가 기본이고, 그때 이 줄이 유일한 정보다.
+ */
+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, 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, Inspector, type InspectorChange, type InspectorProps, type NodeId, PAGE_ID_PATTERN, PageExistsError, PageGoneError, PageIdConflictError, PageIdRejectedError, PageListView, type PageListViewProps, type PageMeta, type PageRecord, type PageRevision, type PageTemplate, Palette, type PaletteProps, 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, bindingContextFor, breadcrumbOf, buildStateKeyIndex, builderFidelity, canDrop, canDropAt, canMoveTo, canRedo, canUndo, createBindingContext, createBindingSource, createEditorState, createRestSpecStore, describeChild, dropFrequency, dropTargetsAround, duplicate, editorReducer, editorRegistry, emptyDoc, flattenTree, formatAction, formatActionList, formatValue, fromPage, getChild, getNode, gradeIssues, inDocumentOrder, insert, isDescendantOf, isMultiSelection, isSelected, isTypingTarget, isValidPageId, looksLikeActionProp, move, readActionList, recommendedChildren, redoLabel, remove, replaceChild, sameInsertionPoint, sameSpecMeaning, setChildren, setNodeKey, setPageMeta, setProp, setProps, setText, slotsOf, specOf, stateKeyStatus, suggestStateKeys, titleOf, toPage, toSpec, topmost, undoLabel, useUndoRedoShortcuts, walkDoc, writeActionList };