@underdogai/mesh-event-schemas 0.2.0 → 0.6.0

package/dist/blocks.d.ts

@@ -3,7 +3,7 @@
  *
  * 설계 원칙 (docs/custom-event-ui.md 참조):
  *  - 닫힌(화이트리스트) 컴포넌트 집합. 임의 HTML/코드 실행 없음.
- *  - 순수 데이터(JSON). 렌더는 @chatops/ui-blocks(React)가 담당.
+ *  - 순수 데이터(JSON). 렌더는 @chatops/spec-renderer(React)가 담당.
  *  - 알 수 없는 블록 타입은 클라이언트가 안전한 fallback으로 렌더.
  *  - 권한은 절대 클라이언트가 아니라 appservice(서버측)가 재검증한다. 여기 disabled/confirm은 UX일 뿐.
  *
@@ -36,7 +36,16 @@ export type Confirm = z.infer<typeof ConfirmSchema>;
 export declare const TextBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
-    /** true면 안전 화이트리스트 마크다운으로 렌더 (raw HTML 금지) */
+    /**
+     * true면 안전 화이트리스트 마크다운으로 렌더 (raw HTML 금지).
+     *
+     * 인라인: `**굵게**` `*기울임*` `` `코드` `` `[텍스트](http…)`.
+     * 블록: 문단(빈 줄) · 목록(`-` `*` `+` / `1.`, 중첩 가능) · 제목(`#`~`###`) · 인용(`>`) ·
+     *       구분선(`---`) · 펜스 코드(``` ```` ```).
+     * 표는 지원하지 않는다 — 표는 `table` 블록이 따로 있다.
+     *
+     * 플래그를 안 주면 평문이다(줄바꿈만 살아난다). 긴 글에는 켜는 쪽이 읽힌다 — #581.
+     */
     markdown: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
@@ -74,14 +83,40 @@ export declare const FieldsBlockSchema: z.ZodObject<{
         value: z.ZodString;
         /** true면 2열 그리드에 좁게 배치 */
         short: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * 값을 색이 다른 조각으로 나눠 그린다 — git diff 의 `+214 −37` 처럼 한 필드 안에서 조각마다
+         * 톤이 달라야 할 때. 있으면 렌더러가 value 대신 이걸 그리고, `value` 는 평문 사본으로 남는다
+         * (구버전 렌더러·fallback 경로가 계속 읽는다 — 그래서 여기 텍스트를 이어붙인 것과 같아야 한다).
+         *
+         * 조각은 gap 으로 벌어진 한 줄이다. 문장을 쪼개는 용도가 아니라 값 옆에 값을 붙이는 용도다.
+         * 색만으로 구분하지 않도록 부호·단위를 각 조각 text 에 남길 것 — 톤은 보조 신호다.
+         */
+        parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }, {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }, {
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "fields";
@@ -89,6 +124,10 @@ export declare const FieldsBlockSchema: z.ZodObject<{
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }[];
 }, {
     type: "fields";
@@ -96,6 +135,10 @@ export declare const FieldsBlockSchema: z.ZodObject<{
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }[];
 }>;
 export declare const ImageBlockSchema: z.ZodObject<{
@@ -277,7 +320,12 @@ export declare const SliderBlockSchema: z.ZodObject<{
     unit?: string | undefined;
 }>;
 export type SliderBlock = z.infer<typeof SliderBlockSchema>;
-/** 단일 선택 라디오 그룹. select 와 달리 옵션이 펼쳐져 보인다. */
+/** 단일 선택 라디오 그룹. select 와 달리 옵션이 펼쳐져 보인다.
+ *  옵션 `hint` = 라벨 아래 한 줄 보조 설명(선택) — "버그 — 뭔가 잘못 동작해요" 처럼 라벨에 설명을
+ *  욱여넣던 것을 두 줄로 가른다(가독성). 옛 클라는 zod 가 벗겨내므로 라벨만 보인다(하위호환).
+ *  `style` = 표현 힌트(선택): "cards" 는 옵션을 전체폭 카드 행으로, "segmented" 는 한 줄 세그먼트로
+ *  (짧은 라벨 전용 — 렌더러가 hint 를 숨긴다). 값 의미는 동일하고 옛 클라는 평 라디오로 그린다.
+ *  ⚠️ 위치 선택자(:first-child)로 특정 폼만 다르게 칠하지 말 것 — 표현은 이 필드로 선언한다. */
 export declare const RadioBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"radio">;
     name: z.ZodString;
@@ -285,32 +333,40 @@ export declare const RadioBlockSchema: z.ZodObject<{
     options: z.ZodArray<z.ZodObject<{
         value: z.ZodString;
         label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
+        hint?: string | undefined;
     }, {
         value: string;
         label: string;
+        hint?: string | undefined;
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<["cards", "segmented"]>>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
         label: string;
+        hint?: string | undefined;
     }[];
     type: "radio";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    style?: "cards" | "segmented" | undefined;
 }, {
     options: {
         value: string;
         label: string;
+        hint?: string | undefined;
     }[];
     type: "radio";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    style?: "cards" | "segmented" | undefined;
 }>;
 export declare const SelectBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"select">;
@@ -368,6 +424,51 @@ export declare const CheckboxBlockSchema: z.ZodObject<{
     name: string;
     checked?: boolean | undefined;
 }>;
+/**
+ * 위치 입력 — "지금 내 위치" 한 번을 **사용자 제스처로** 받아 폼 값으로 수집한다.
+ *
+ * 왜 입력 블록인가: 위치는 앱이 가져가는 게 아니라 **사람이 주는 것**이다. 그래서 다른 입력과 같은
+ * 자리에 서고(name 으로 수집 → 제출 버튼의 values 에 실림), 카드/모달 어느 쪽에도 놓을 수 있다.
+ * 버튼을 누르는 순간 OS 권한창이 뜨므로 "위치 권한 수락"과 "현재 위치 가져오기"가 한 동작이다 —
+ * 웹에는 애초에 "권한만 요청" 하는 API 가 없고, 네이티브도 쓰지 않을 권한을 미리 묻는 앱은 심사에서
+ * 이유를 설명해야 한다. 그래서 **쓸 때 묻는다**.
+ *
+ * 값의 모양은 `LocationValue`(geo.ts) — 좌표는 문자열 geo URI 다(canonical JSON 소수 금지).
+ * 수집 전에는 `""`. 못 쓰는 클라(구 셸·위치 없는 브라우저)에서는 렌더러가 **버튼을 비활성 + 이유**로
+ * degrade 한다 → 누른 뒤에 실패를 알게 되지 않는다.
+ */
+export declare const LocationBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"location">;
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    /**
+     * 왜 필요한지 한 줄 — **OS 권한창보다 먼저** 보인다. 시스템 문구(Info.plist·Android 권한창)는
+     * 앱 전체에 하나뿐이라 이 카드가 왜 묻는지는 여기서만 말할 수 있다(그리고 그게 심사가 보는 것이다).
+     */
+    purpose: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    /** GPS 급 정확도로 받을지(느리고 배터리를 더 쓴다). 기본 false = 네트워크/대략 위치. */
+    precise: z.ZodOptional<z.ZodBoolean>;
+    /** 버튼 문구(작성자 소유 문장). 미지정이면 렌더러 크롬 문구를 쓴다. */
+    buttonText: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "location";
+    name: string;
+    label?: string | undefined;
+    required?: boolean | undefined;
+    purpose?: string | undefined;
+    precise?: boolean | undefined;
+    buttonText?: string | undefined;
+}, {
+    type: "location";
+    name: string;
+    label?: string | undefined;
+    required?: boolean | undefined;
+    purpose?: string | undefined;
+    precise?: boolean | undefined;
+    buttonText?: string | undefined;
+}>;
+export type LocationBlock = z.infer<typeof LocationBlockSchema>;
 export declare const ButtonBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"button">;
     /** 어떤 액션인지 식별. 클릭 시 org.corp.ui.action.action_id 로 회신됨. */
@@ -393,6 +494,19 @@ export declare const ButtonBlockSchema: z.ZodObject<{
         cancel?: string | undefined;
     }>>;
     disabled: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 이 MXID 들에게는 버튼을 **감춘다**(뷰어별 어포던스).
+     *
+     * 왜 필요한가: 카드 한 장은 방 전체가 같이 본다. 그런데 "이 사람만 절대 못 누르는 버튼"이 있다 —
+     * Forgejo 는 **자기 PR 자기 승인**을 422 로 거절한다(`approve your own pull is not allowed`).
+     * 그래서 작성자에게 Approve 를 보여 주면 눌러도 실패 카드만 쌓인다. 카드 전체에서 버튼을 빼면
+     * 남들이 승인을 못 하므로, 판정은 **보는 사람별**이어야 한다.
+     *
+     * 🔴 **권한이 아니다.** 진짜 게이트는 언제나 서버다(disabled/confirm 과 같은 자세) — 이건 없는
+     * 어포던스를 안 보여 주기 위한 것뿐이다. 그래서 이 키를 모르는 옛 클라이언트가 버튼을 그대로
+     * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
+     */
+    hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "button";
     text: string;
@@ -406,6 +520,7 @@ export declare const ButtonBlockSchema: z.ZodObject<{
         cancel?: string | undefined;
     } | undefined;
     disabled?: boolean | undefined;
+    hidden_for?: string[] | undefined;
 }, {
     type: "button";
     text: string;
@@ -419,6 +534,7 @@ export declare const ButtonBlockSchema: z.ZodObject<{
         cancel?: string | undefined;
     } | undefined;
     disabled?: boolean | undefined;
+    hidden_for?: string[] | undefined;
 }>;
 export type ButtonBlock = z.infer<typeof ButtonBlockSchema>;
 /**
@@ -475,6 +591,19 @@ export declare const ActionsBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         }>>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * 이 MXID 들에게는 버튼을 **감춘다**(뷰어별 어포던스).
+         *
+         * 왜 필요한가: 카드 한 장은 방 전체가 같이 본다. 그런데 "이 사람만 절대 못 누르는 버튼"이 있다 —
+         * Forgejo 는 **자기 PR 자기 승인**을 422 로 거절한다(`approve your own pull is not allowed`).
+         * 그래서 작성자에게 Approve 를 보여 주면 눌러도 실패 카드만 쌓인다. 카드 전체에서 버튼을 빼면
+         * 남들이 승인을 못 하므로, 판정은 **보는 사람별**이어야 한다.
+         *
+         * 🔴 **권한이 아니다.** 진짜 게이트는 언제나 서버다(disabled/confirm 과 같은 자세) — 이건 없는
+         * 어포던스를 안 보여 주기 위한 것뿐이다. 그래서 이 키를 모르는 옛 클라이언트가 버튼을 그대로
+         * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
+         */
+        hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         type: "button";
         text: string;
@@ -488,6 +617,7 @@ export declare const ActionsBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     }, {
         type: "button";
         text: string;
@@ -501,6 +631,7 @@ export declare const ActionsBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"linkButton">;
         text: z.ZodString;
@@ -537,6 +668,7 @@ export declare const ActionsBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     } | {
         type: "linkButton";
         text: string;
@@ -559,6 +691,7 @@ export declare const ActionsBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     } | {
         type: "linkButton";
         text: string;
@@ -658,23 +791,27 @@ export declare const OverflowBlockSchema: z.ZodObject<{
     label?: string | undefined;
 }>;
 export type OverflowBlock = z.infer<typeof OverflowBlockSchema>;
-/** 진행률 바 (0~100). 에이전트가 m.replace 편집으로 갱신해 "스트리밍" 진행 표시 가능. */
+/**
+ * 진행률 바 (0~100). 에이전트가 m.replace 편집으로 갱신해 "스트리밍" 진행 표시 가능.
+ *
+ * 🔴 **톤 축이 없다** — 배지·콜아웃·메트릭과 갈리는 자리다. 이 블록의 렌더러는 shadcn `Progress`
+ * 이고 채움 색이 `bg-primary` 하나뿐이라(라이브러리에 그 축이 없다) 톤을 받아 봐야 그릴 곳이 없다.
+ * 색을 넣고 싶으면 스키마가 아니라 **렌더러부터** 물을 것(`docs/cob-to-shadcn-map.md` 의 `progress` 행).
+ * 진행 바 옆에서 성패를 말해야 하면 `label` 이나 형제 `badge`·`callout` 블록이 그 자리다.
+ */
 export declare const ProgressBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"progress">;
     /** 0~100 백분율(정수). 생략하면 indeterminate(불확정) 표시. 와이어 canonical JSON 은 소수 금지 → int 강제. */
     value: z.ZodOptional<z.ZodNumber>;
     label: z.ZodOptional<z.ZodString>;
-    tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "progress";
     value?: number | undefined;
     label?: string | undefined;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }, {
     type: "progress";
     value?: number | undefined;
     label?: string | undefined;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }>;
 /** 멀티스텝 진행 상태 표시(타임라인). 폼 마법사와 별개로, 작업 단계 시각화에 쓴다. */
 export declare const StepsBlockSchema: z.ZodObject<{
@@ -867,21 +1004,26 @@ export declare const ChartBlockSchema: z.ZodObject<{
     caption?: string | undefined;
 }>;
 export type ChartBlock = z.infer<typeof ChartBlockSchema>;
-/** 단일 아바타 — 얼굴 동그라미(이미지/이니셜) + 이름·보조텍스트 + 상태점. 담당자 표시. */
+/**
+ * 단일 아바타 — 얼굴 동그라미(이미지/이니셜) + 이름·보조텍스트 + 상태점. 담당자 표시.
+ *
+ * 🔴 **`color` 는 뺐다**(0.6.0). 이니셜 면은 shadcn `AvatarFallback` 의 `bg-muted` 한 벌이고
+ * 렌더러엔 그 색을 받을 자리가 없다 — 계약에 두면 작성자가 보내고 아무 일도 안 일어난다
+ * (`progress.tone` 을 뺀 것과 같은 이유). 누구인지는 이니셜·이름·프로필 사진이 나른다.
+ */
 export declare const AvatarBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"avatar">;
     name: z.ZodString;
     initials: z.ZodOptional<z.ZodString>;
-    color: z.ZodOptional<z.ZodString>;
     src: z.ZodOptional<z.ZodString>;
     subtitle: z.ZodOptional<z.ZodString>;
+    /** 우하단 상태점 — 네 상태가 각자 색을 갖는다(`--cob-color-presence-*`). 색만으로 안 나르도록 `aria-label` 이 상태를 병기한다. */
     status: z.ZodOptional<z.ZodEnum<["online", "away", "busy", "offline"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "avatar";
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
     initials?: string | undefined;
-    color?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
 }, {
@@ -889,7 +1031,6 @@ export declare const AvatarBlockSchema: z.ZodObject<{
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
     initials?: string | undefined;
-    color?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
 }>;
@@ -901,19 +1042,15 @@ export declare const AvatarGroupBlockSchema: z.ZodObject<{
         name: z.ZodString;
         /** 이니셜(미지정 시 name 에서 자동 생성). */
         initials: z.ZodOptional<z.ZodString>;
-        /** 배경색(CSS 색/토큰). 미지정 시 name 해시로 팔레트에서 고름. */
-        color: z.ZodOptional<z.ZodString>;
         /** 이미지 URL(https). 있으면 이미지, 없으면 이니셜. */
         src: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }, {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }>, "many">;
     /** 앞에서 몇 명까지 보일지(기본 5). 나머지는 +N. */
@@ -924,7 +1061,6 @@ export declare const AvatarGroupBlockSchema: z.ZodObject<{
     people: {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }[];
     label?: string | undefined;
@@ -934,7 +1070,6 @@ export declare const AvatarGroupBlockSchema: z.ZodObject<{
     people: {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }[];
     label?: string | undefined;
@@ -1006,14 +1141,14 @@ export declare const CalloutBlockSchema: z.ZodObject<{
     type: "callout";
     text: string;
     title?: string | undefined;
-    icon?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    icon?: string | undefined;
 }, {
     type: "callout";
     text: string;
     title?: string | undefined;
-    icon?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    icon?: string | undefined;
 }>;
 export type CalloutBlock = z.infer<typeof CalloutBlockSchema>;
 /** 엔티티 참조 칩 — 엔티티(송장·리드·repo…)로의 라벨/링크 칩. url 있으면 링크. */
@@ -1028,14 +1163,14 @@ export declare const EntityRefBlockSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "entityRef";
     label: string;
-    url?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    url?: string | undefined;
     entity?: string | undefined;
 }, {
     type: "entityRef";
     label: string;
-    url?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    url?: string | undefined;
     entity?: string | undefined;
 }>;
 export type EntityRefBlock = z.infer<typeof EntityRefBlockSchema>;
@@ -1069,49 +1204,49 @@ export declare const KanbanBlockSchema: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }, {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }, {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }>, "many">;
     caption: z.ZodOptional<z.ZodString>;
@@ -1119,17 +1254,17 @@ export declare const KanbanBlockSchema: z.ZodObject<{
     type: "kanban";
     columns: {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1137,17 +1272,17 @@ export declare const KanbanBlockSchema: z.ZodObject<{
     type: "kanban";
     columns: {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1252,7 +1387,16 @@ export declare const WidgetBlockSchema: z.ZodObject<{
 export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
-    /** true면 안전 화이트리스트 마크다운으로 렌더 (raw HTML 금지) */
+    /**
+     * true면 안전 화이트리스트 마크다운으로 렌더 (raw HTML 금지).
+     *
+     * 인라인: `**굵게**` `*기울임*` `` `코드` `` `[텍스트](http…)`.
+     * 블록: 문단(빈 줄) · 목록(`-` `*` `+` / `1.`, 중첩 가능) · 제목(`#`~`###`) · 인용(`>`) ·
+     *       구분선(`---`) · 펜스 코드(``` ```` ```).
+     * 표는 지원하지 않는다 — 표는 `table` 블록이 따로 있다.
+     *
+     * 플래그를 안 주면 평문이다(줄바꿈만 살아난다). 긴 글에는 켜는 쪽이 읽힌다 — #581.
+     */
     markdown: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
@@ -1287,14 +1431,40 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         value: z.ZodString;
         /** true면 2열 그리드에 좁게 배치 */
         short: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * 값을 색이 다른 조각으로 나눠 그린다 — git diff 의 `+214 −37` 처럼 한 필드 안에서 조각마다
+         * 톤이 달라야 할 때. 있으면 렌더러가 value 대신 이걸 그리고, `value` 는 평문 사본으로 남는다
+         * (구버전 렌더러·fallback 경로가 계속 읽는다 — 그래서 여기 텍스트를 이어붙인 것과 같아야 한다).
+         *
+         * 조각은 gap 으로 벌어진 한 줄이다. 문장을 쪼개는 용도가 아니라 값 옆에 값을 붙이는 용도다.
+         * 색만으로 구분하지 않도록 부호·단위를 각 조각 text 에 남길 것 — 톤은 보조 신호다.
+         */
+        parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }, {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }, {
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "fields";
@@ -1302,6 +1472,10 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }[];
 }, {
     type: "fields";
@@ -1309,6 +1483,10 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         value: string;
         label: string;
         short?: boolean | undefined;
+        parts?: {
+            text: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        }[] | undefined;
     }[];
 }>, z.ZodObject<{
     type: z.ZodLiteral<"image">;
@@ -1385,17 +1563,14 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     /** 0~100 백분율(정수). 생략하면 indeterminate(불확정) 표시. 와이어 canonical JSON 은 소수 금지 → int 강제. */
     value: z.ZodOptional<z.ZodNumber>;
     label: z.ZodOptional<z.ZodString>;
-    tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "progress";
     value?: number | undefined;
     label?: string | undefined;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }, {
     type: "progress";
     value?: number | undefined;
     label?: string | undefined;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"steps">;
     items: z.ZodArray<z.ZodObject<{
@@ -1497,16 +1672,15 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"avatar">;
     name: z.ZodString;
     initials: z.ZodOptional<z.ZodString>;
-    color: z.ZodOptional<z.ZodString>;
     src: z.ZodOptional<z.ZodString>;
     subtitle: z.ZodOptional<z.ZodString>;
+    /** 우하단 상태점 — 네 상태가 각자 색을 갖는다(`--cob-color-presence-*`). 색만으로 안 나르도록 `aria-label` 이 상태를 병기한다. */
     status: z.ZodOptional<z.ZodEnum<["online", "away", "busy", "offline"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "avatar";
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
     initials?: string | undefined;
-    color?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
 }, {
@@ -1514,7 +1688,6 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
     initials?: string | undefined;
-    color?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
 }>, z.ZodObject<{
@@ -1523,19 +1696,15 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         name: z.ZodString;
         /** 이니셜(미지정 시 name 에서 자동 생성). */
         initials: z.ZodOptional<z.ZodString>;
-        /** 배경색(CSS 색/토큰). 미지정 시 name 해시로 팔레트에서 고름. */
-        color: z.ZodOptional<z.ZodString>;
         /** 이미지 URL(https). 있으면 이미지, 없으면 이니셜. */
         src: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }, {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }>, "many">;
     /** 앞에서 몇 명까지 보일지(기본 5). 나머지는 +N. */
@@ -1546,7 +1715,6 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     people: {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }[];
     label?: string | undefined;
@@ -1556,7 +1724,6 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     people: {
         name: string;
         initials?: string | undefined;
-        color?: string | undefined;
         src?: string | undefined;
     }[];
     label?: string | undefined;
@@ -1619,14 +1786,14 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "callout";
     text: string;
     title?: string | undefined;
-    icon?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    icon?: string | undefined;
 }, {
     type: "callout";
     text: string;
     title?: string | undefined;
-    icon?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    icon?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"entityRef">;
     label: z.ZodString;
@@ -1638,14 +1805,14 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "entityRef";
     label: string;
-    url?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    url?: string | undefined;
     entity?: string | undefined;
 }, {
     type: "entityRef";
     label: string;
-    url?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+    url?: string | undefined;
     entity?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"kanban">;
@@ -1672,49 +1839,49 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }, {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }, {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }>, "many">;
     caption: z.ZodOptional<z.ZodString>;
@@ -1722,17 +1889,17 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "kanban";
     columns: {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1740,17 +1907,17 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "kanban";
     columns: {
         title: string;
-        id: string;
         cards: {
             title: string;
             id: string;
+            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             } | undefined;
-            tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             meta?: string[] | undefined;
         }[];
+        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1988,32 +2155,40 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     options: z.ZodArray<z.ZodObject<{
         value: z.ZodString;
         label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
+        hint?: string | undefined;
     }, {
         value: string;
         label: string;
+        hint?: string | undefined;
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<["cards", "segmented"]>>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
         label: string;
+        hint?: string | undefined;
     }[];
     type: "radio";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    style?: "cards" | "segmented" | undefined;
 }, {
     options: {
         value: string;
         label: string;
+        hint?: string | undefined;
     }[];
     type: "radio";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    style?: "cards" | "segmented" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"select">;
     name: z.ZodString;
@@ -2068,6 +2243,36 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     label: string;
     name: string;
     checked?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"location">;
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    /**
+     * 왜 필요한지 한 줄 — **OS 권한창보다 먼저** 보인다. 시스템 문구(Info.plist·Android 권한창)는
+     * 앱 전체에 하나뿐이라 이 카드가 왜 묻는지는 여기서만 말할 수 있다(그리고 그게 심사가 보는 것이다).
+     */
+    purpose: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    /** GPS 급 정확도로 받을지(느리고 배터리를 더 쓴다). 기본 false = 네트워크/대략 위치. */
+    precise: z.ZodOptional<z.ZodBoolean>;
+    /** 버튼 문구(작성자 소유 문장). 미지정이면 렌더러 크롬 문구를 쓴다. */
+    buttonText: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "location";
+    name: string;
+    label?: string | undefined;
+    required?: boolean | undefined;
+    purpose?: string | undefined;
+    precise?: boolean | undefined;
+    buttonText?: string | undefined;
+}, {
+    type: "location";
+    name: string;
+    label?: string | undefined;
+    required?: boolean | undefined;
+    purpose?: string | undefined;
+    precise?: boolean | undefined;
+    buttonText?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"button">;
     /** 어떤 액션인지 식별. 클릭 시 org.corp.ui.action.action_id 로 회신됨. */
@@ -2093,6 +2298,19 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         cancel?: string | undefined;
     }>>;
     disabled: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 이 MXID 들에게는 버튼을 **감춘다**(뷰어별 어포던스).
+     *
+     * 왜 필요한가: 카드 한 장은 방 전체가 같이 본다. 그런데 "이 사람만 절대 못 누르는 버튼"이 있다 —
+     * Forgejo 는 **자기 PR 자기 승인**을 422 로 거절한다(`approve your own pull is not allowed`).
+     * 그래서 작성자에게 Approve 를 보여 주면 눌러도 실패 카드만 쌓인다. 카드 전체에서 버튼을 빼면
+     * 남들이 승인을 못 하므로, 판정은 **보는 사람별**이어야 한다.
+     *
+     * 🔴 **권한이 아니다.** 진짜 게이트는 언제나 서버다(disabled/confirm 과 같은 자세) — 이건 없는
+     * 어포던스를 안 보여 주기 위한 것뿐이다. 그래서 이 키를 모르는 옛 클라이언트가 버튼을 그대로
+     * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
+     */
+    hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "button";
     text: string;
@@ -2106,6 +2324,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         cancel?: string | undefined;
     } | undefined;
     disabled?: boolean | undefined;
+    hidden_for?: string[] | undefined;
 }, {
     type: "button";
     text: string;
@@ -2119,6 +2338,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         cancel?: string | undefined;
     } | undefined;
     disabled?: boolean | undefined;
+    hidden_for?: string[] | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"linkButton">;
     text: z.ZodString;
@@ -2166,6 +2386,19 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         }>>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * 이 MXID 들에게는 버튼을 **감춘다**(뷰어별 어포던스).
+         *
+         * 왜 필요한가: 카드 한 장은 방 전체가 같이 본다. 그런데 "이 사람만 절대 못 누르는 버튼"이 있다 —
+         * Forgejo 는 **자기 PR 자기 승인**을 422 로 거절한다(`approve your own pull is not allowed`).
+         * 그래서 작성자에게 Approve 를 보여 주면 눌러도 실패 카드만 쌓인다. 카드 전체에서 버튼을 빼면
+         * 남들이 승인을 못 하므로, 판정은 **보는 사람별**이어야 한다.
+         *
+         * 🔴 **권한이 아니다.** 진짜 게이트는 언제나 서버다(disabled/confirm 과 같은 자세) — 이건 없는
+         * 어포던스를 안 보여 주기 위한 것뿐이다. 그래서 이 키를 모르는 옛 클라이언트가 버튼을 그대로
+         * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
+         */
+        hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         type: "button";
         text: string;
@@ -2179,6 +2412,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     }, {
         type: "button";
         text: string;
@@ -2192,6 +2426,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"linkButton">;
         text: z.ZodString;
@@ -2228,6 +2463,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     } | {
         type: "linkButton";
         text: string;
@@ -2250,6 +2486,7 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
     } | {
         type: "linkButton";
         text: string;