@underdogai/mesh-event-schemas 0.6.0 → 0.9.0

package/dist/blocks.d.ts

@@ -15,6 +15,56 @@ export declare const ToneSchema: z.ZodEnum<["neutral", "success", "warning", "da
 export type Tone = z.infer<typeof ToneSchema>;
 export declare const ButtonStyleSchema: z.ZodEnum<["default", "primary", "danger"]>;
 export type ButtonStyle = z.infer<typeof ButtonStyleSchema>;
+/**
+ * **참조 값**(0.8.0) — 사람·엔티티를 문자열이 아니라 가리키는 값으로 싣는다.
+ *
+ * 왜 필요한가: 같은 사람이 카드 안에서 세 표기로 흩어진다 — fields 의 "현호 손", 옵션 라벨
+ * "goya@bluepinlabs.com", 이력의 "heetae". 앱이 서버에서 표시명을 만들어 문자열로 박기 때문인데,
+ * 그러면 형식이 갈리고 얼굴이 없고 개명·동명이인에 취약하다. 값이 **MXID 참조**이고 클라가 방 상태로
+ * 이름·아바타를 해석하면, 어느 블록에 놓여도 같은 얼굴로 선다.
+ *
+ * 🔴 **평문 사본은 남는다**(`fields.parts` 와 같은 규칙 — §4). `ref` 를 모르는 옛 클라는 이 키를
+ * zod strip 으로 벗기고 `value`/`label`/`name` 문자열을 지금처럼 그린다. 그래서 참조를 실으면서도
+ * 사본을 비우면 **그 필드가 빈칸이 된다** — 사본은 선택이 아니라 계약이다.
+ *
+ * 🔴 **이것도 권한이 아니다.** 값이 MXID 라는 것은 서버가 멤버십으로 재검증할 수 있다는 뜻이지,
+ * 클라가 신원을 판정한다는 뜻이 아니다.
+ */
+export declare const RefSchema: z.ZodUnion<[z.ZodObject<{
+    /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+    user: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    user: string;
+}, {
+    user: string;
+}>, z.ZodObject<{
+    /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+    entity: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+    }, {
+        type: string;
+        id: string;
+    }>;
+    /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+    url: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entity: {
+        type: string;
+        id: string;
+    };
+    url?: string | undefined;
+}, {
+    entity: {
+        type: string;
+        id: string;
+    };
+    url?: string | undefined;
+}>]>;
+export type Ref = z.infer<typeof RefSchema>;
 /** 파괴적 액션 전에 클라이언트가 띄우는 확인 다이얼로그. 서버도 별도로 HITL 재검증한다. */
 export declare const ConfirmSchema: z.ZodObject<{
     title: z.ZodString;
@@ -101,6 +151,54 @@ export declare const FieldsBlockSchema: z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }>, "many">>;
+        /**
+         * 이 값이 가리키는 사람/엔티티 (0.8.0). 있으면 렌더러가 칩(아바타+이름 / 종류+라벨)으로 그린다.
+         * 🔴 **`value` 는 평문 사본으로 남긴다** — `parts` 와 같은 규칙이다(RefSchema 머리말).
+         */
+        ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>>;
+        /**
+         * **이 항목은 문단이다**(0.9.0) — 값이 아니라 본문. 전체폭으로 서고 값 서체(600)를 풀며
+         * 인라인 마크다운을 그린다.
+         *
+         * 왜 필요한가(감사 문서 D): "막힌 일: ㅁㄴㄹ…" 같은 자유 서술이 지금은 굵은 값 서체로 서서
+         * 숫자·상태와 같은 무게로 읽힌다. 작성자가 `short` 로 열 수를 강제하던 것과 같은 자리 —
+         * 작성자는 "이건 문단이다"만 말하고 폭·서체는 렌더러가 정한다.
+         * ⚠️ `short` 와 같이 주면 `long` 이 이긴다(반폭 문단은 없다).
+         */
+        long: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
@@ -109,6 +207,16 @@ export declare const FieldsBlockSchema: z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }, {
         value: string;
         label: string;
@@ -117,7 +225,26 @@ export declare const FieldsBlockSchema: z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }>, "many">;
+    /**
+     * 열 수 **명시 오버라이드**(0.9.0). 생략이 기본이고, 기본은 폭이 정하는 auto-fit 이다
+     * (그리고 `short` 넷이면 2×2 로 묶인다 — 0.7.0 에서 이미 들어간 규칙).
+     *
+     * 🔴 **기본을 되돌리지 않는다.** 이 키는 auto-fit 이 틀리는 드문 경우(라벨이 길어 3열이 찢어지는
+     * 표 같은 fields)를 위한 탈출구다 — 늘 주면 좁은 화면에서 열이 안 줄어 값이 짜부라진다.
+     * `"auto"` 는 명시적으로 기본을 고르는 값이다(작성자가 "여긴 렌더러에 맡긴다"를 적을 수 있게).
+     */
+    columns: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<"auto">]>>;
 }, "strip", z.ZodTypeAny, {
     type: "fields";
     items: {
@@ -128,7 +255,18 @@ export declare const FieldsBlockSchema: z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }[];
+    columns?: 2 | 3 | "auto" | undefined;
 }, {
     type: "fields";
     items: {
@@ -139,7 +277,18 @@ export declare const FieldsBlockSchema: z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }[];
+    columns?: 2 | 3 | "auto" | undefined;
 }>;
 export declare const ImageBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"image">;
@@ -158,9 +307,18 @@ export declare const ImageBlockSchema: z.ZodObject<{
     mxc?: string | undefined;
     alt?: string | undefined;
 }>;
+/**
+ * 작은 보조 텍스트/아이콘 줄.
+ *
+ * ⬜ **여기엔 `ref` 원소를 안 둔다(0.8.0에서 일부러 뺐다).** 다른 자리의 참조는 *기존 객체의 새 키*라
+ * 옛 클라가 zod strip 으로 벗기고 평문 사본을 그리지만, 여기 `elements` 는 **닫힌 유니온**이라 새
+ * 모양의 원소 하나가 유니온 전체를 실패시키고 → 배열이 실패하고 → `dropUnknownBlocks` 가 **context
+ * 블록을 통째로 떨군다**. 즉 "평문 사본이 곁에 선다"는 규칙이 성립하지 않는 유일한 자리다
+ * (`parts`·`hidden_for`·`ref` 가 다 되는 이유가 그 셋은 키 추가이기 때문이다).
+ * 사람을 보조 줄에 그리고 싶으면 `activity` 블록이나 `fields` 항목의 `ref` 를 쓴다.
+ */
 export declare const ContextBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"context">;
-    /** 작은 보조 텍스트/아이콘 줄 */
     elements: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         icon: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -237,26 +395,68 @@ export declare const InputBlockSchema: z.ZodObject<{
      * 단일 업로드로 동작한다(기능 축소일 뿐 파손 없음).
      */
     multiple: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 하한/상한 (0.7.0) — number/date/datetime/time 공용. **문자열**이다: 날짜·시각은 그 타입의 값
+     * 형식(`2026-09-22`·`18:15`)이고, number 면 숫자를 적은 문자열이다(와이어 canonical JSON 은
+     * 소수를 허용하지 않아 숫자 축을 열 수 없다 — `slider` 가 int 만 받는 것과 같은 제약).
+     *
+     * `"today"` 리터럴을 허용한다 — "기한은 오늘 이후"는 카드를 **보낸 날**이 아니라 **보는 날** 기준이라야
+     * 맞다(카드는 타임라인에 남고 며칠 뒤에도 눌린다). 렌더러가 그릴 때 해석한다.
+     *
+     * 🔴 **UX 다, 진실은 서버**(`hidden_for` 와 같은 자세). 클라가 미리 잠그는 건 헛걸음을 줄이려는
+     * 것뿐이고, 진짜 판정은 언제나 핸들러·게이트가 한다. 이 키를 모르는 옛 클라는 strip 하고 지금처럼
+     * 아무 제약 없이 제출한다 — 그러면 서버가 사람이 읽을 이유와 함께 거절한다(`action.result`).
+     */
+    min: z.ZodOptional<z.ZodString>;
+    max: z.ZodOptional<z.ZodString>;
+    /** 글자 수 하한/상한 (0.7.0) — 텍스트 계열 전용. 🔴 UX 다, 진실은 서버. */
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    /**
+     * 값이 맞아야 하는 정규식 **소스**(0.7.0, 예: `"^[A-Z]{2}-\\d{4}$"`). 플래그·구분자 없이 패턴만 적는다.
+     *
+     * 🔴 렌더러는 `new RegExp` 를 **try/catch 로 감싼다** — 작성자가 자바스크립트가 아닌 방언(파이썬
+     * `(?P<x>…)` 등)을 보내면 던지는데, 그걸로 카드 전체가 죽으면 안 된다. 못 읽는 패턴은 무시한다
+     * (= 제약 없음). 진짜 판정은 여전히 서버다.
+     */
+    pattern: z.ZodOptional<z.ZodString>;
+    /**
+     * 제약 위반 시 보여 줄 **작성자 소유 문장**(0.7.0). 없으면 렌더러 크롬 문구를 쓴다
+     * (`LabelContext` — "누구의 문자열인가"가 경계선이고, 도메인 사정을 아는 문장은 작성자 것이다).
+     */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "input";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
-    input?: "number" | "text" | "date" | "url" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
+    input?: "number" | "date" | "url" | "text" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
     placeholder?: string | undefined;
     required?: boolean | undefined;
     accept?: string | undefined;
     multiple?: boolean | undefined;
+    min?: string | undefined;
+    max?: string | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    pattern?: string | undefined;
+    error?: string | undefined;
 }, {
     type: "input";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
-    input?: "number" | "text" | "date" | "url" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
+    input?: "number" | "date" | "url" | "text" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
     placeholder?: string | undefined;
     required?: boolean | undefined;
     accept?: string | undefined;
     multiple?: boolean | undefined;
+    min?: string | undefined;
+    max?: string | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    pattern?: string | undefined;
+    error?: string | undefined;
 }>;
 /** 토글(스위치) — checkbox 와 같은 불리언을 수집하되 on/off 스위치 어포던스로 렌더. */
 export declare const ToggleBlockSchema: z.ZodObject<{
@@ -325,7 +525,13 @@ export type SliderBlock = z.infer<typeof SliderBlockSchema>;
  *  욱여넣던 것을 두 줄로 가른다(가독성). 옛 클라는 zod 가 벗겨내므로 라벨만 보인다(하위호환).
  *  `style` = 표현 힌트(선택): "cards" 는 옵션을 전체폭 카드 행으로, "segmented" 는 한 줄 세그먼트로
  *  (짧은 라벨 전용 — 렌더러가 hint 를 숨긴다). 값 의미는 동일하고 옛 클라는 평 라디오로 그린다.
- *  ⚠️ 위치 선택자(:first-child)로 특정 폼만 다르게 칠하지 말 것 — 표현은 이 필드로 선언한다. */
+ *  ⚠️ 위치 선택자(:first-child)로 특정 폼만 다르게 칠하지 말 것 — 표현은 이 필드로 선언한다.
+ *
+ *  📎 **0.9.0 부터 이것은 `select` 의 별칭이다** — `style: "list"` · `multi` 없음 · `source` 없음의
+ *  `select` 와 **같은 컨트롤로 그려진다**(`spec-renderer/OptionGroup.tsx` 한 벌). 스키마를 합치지
+ *  않는 이유는 둘뿐이다: ① 이미 나간 카드가 `type: "radio"` 로 쌓여 있고, ② `style: "cards"` 는
+ *  라디오에만 있는 표현이다. 새로 쓰는 카드라면 어느 쪽을 골라도 되고, **선택 축이 하나라도 늘면**
+ *  (`multi`·`source`·`searchable`) `select` 로 가야 한다 — 그 축들은 여기 없다. */
 export declare const RadioBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"radio">;
     name: z.ZodString;
@@ -345,6 +551,10 @@ export declare const RadioBlockSchema: z.ZodObject<{
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
     style: z.ZodOptional<z.ZodEnum<["cards", "segmented"]>>;
+    /** 고르지 않으면 제출을 잠근다 (0.7.0). 🔴 UX 다, 진실은 서버 — `input.required` 와 같은 자세. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /** 미선택 시 보여 줄 작성자 소유 문장 (0.7.0). 없으면 렌더러 크롬 문구. */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
@@ -355,6 +565,8 @@ export declare const RadioBlockSchema: z.ZodObject<{
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    required?: boolean | undefined;
+    error?: string | undefined;
     style?: "cards" | "segmented" | undefined;
 }, {
     options: {
@@ -366,48 +578,299 @@ export declare const RadioBlockSchema: z.ZodObject<{
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    required?: boolean | undefined;
+    error?: string | undefined;
     style?: "cards" | "segmented" | undefined;
 }>;
+/**
+ * **후보 공급원**(0.9.0) — 후보가 *어디서 오는가*. 생략하면 `options` 배열이 곧 후보다(지금까지의 동작).
+ *
+ * 왜 축인가: "검색하기" 버튼 + 체크박스 18개 + "사람 더 보기 · 13명" 은 서로 다른 기능이 아니라
+ * **후보가 카드 밖에 있을 때** 작성자가 손으로 만든 우회 UI 다(감사 문서 B). 공급원을 선언으로
+ * 올리면 검색·스크롤·아바타 행은 렌더러가 정한다.
+ *
+ * 🔴 **`source` 를 줘도 `options` 는 계약이다.** 이 키를 모르는 옛 클라는 zod strip 으로 벗기고
+ * `options` 만 그린다 — 비워 보내면 그 클라에서 **고를 것이 없는 select** 가 선다(`ref` 의 평문
+ * 사본과 같은 규칙, `RefSchema` 머리말). 방 멤버는 빌더가 채울 수 없으므로(서버는 방 상태를 모를
+ * 수 있다) 그땐 카드 `fallback` 이 대신 설명해야 한다.
+ */
+export declare const SelectSourceSchema: z.ZodUnion<[z.ZodObject<{
+    /** 이 방의 멤버가 후보다. 값은 MXID 배열이고, 이름·아바타는 클라가 방 상태로 해석한다. */
+    kind: z.ZodLiteral<"room">;
+    /** 보는 사람 자신을 후보에서 뺀다(기본 false). "받을 사람"처럼 나를 고를 일이 없는 자리. */
+    exclude_self: z.ZodOptional<z.ZodBoolean>;
+    /** 후보에서 뺄 MXID 목록 — 이미 담당인 사람, 퇴사 처리 중인 계정 등. */
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** 봇·에이전트 계정도 후보에 넣는다(기본 false — 사람을 고르는 자리가 대부분이다). */
+    include_bots: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    kind: "room";
+    exclude_self?: boolean | undefined;
+    exclude?: string[] | undefined;
+    include_bots?: boolean | undefined;
+}, {
+    kind: "room";
+    exclude_self?: boolean | undefined;
+    exclude?: string[] | undefined;
+    include_bots?: boolean | undefined;
+}>, z.ZodObject<{
+    /** 타이핑할 때마다 서버에 묻는다 — 답은 `org.corp.ui.action.result` 의 `kind: "options"`. */
+    kind: z.ZodLiteral<"query">;
+    /**
+     * 질의를 받을 액션. 클라는 `action_type: "query"` 로 `{ q, name }` 을 실어 보낸다.
+     * 🔴 사람이 누른 게 아니므로 앱은 **부작용 없이** `ctx.result({ kind: "options", name, options })`
+     * 로만 답해야 한다(같은 핸들러가 제출도 처리한다면 `action_type` 으로 갈라야 한다).
+     */
+    action_id: z.ZodString;
+    /** 몇 글자부터 묻나(기본 1). 한 글자에 전체 스캔이 도는 백엔드라면 올린다. */
+    min_chars: z.ZodOptional<z.ZodNumber>;
+    /** 타이핑이 멎고 몇 ms 뒤에 묻나(기본 300). */
+    debounce_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    kind: "query";
+    action_id: string;
+    min_chars?: number | undefined;
+    debounce_ms?: number | undefined;
+}, {
+    kind: "query";
+    action_id: string;
+    min_chars?: number | undefined;
+    debounce_ms?: number | undefined;
+}>]>;
+export type SelectSource = z.infer<typeof SelectSourceSchema>;
+/**
+ * **하나의 선택 모델**(감사 문서 B) — "후보 집합에서 N 개를 고른다"는 일 하나가 세 축으로 선다:
+ * 공급원(`source`) × 개수(`multi`·`min`·`max`) × 표현(`style`·`searchable`).
+ *
+ * 축이 직교라서 사람 선택도, 검색도, "더 보기"도 **새 블록이 아니라 축의 값**이다. 배치 판정
+ * (네이티브냐 콤보박스냐, 칩이냐)은 작성자가 아니라 렌더러가 한다 —
+ * `spec-renderer/chooseModel.ts` 의 `choosePlan` 이 그 판정표를 한 자리에서 갖는다.
+ */
 export declare const SelectBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"select">;
     name: z.ZodString;
     label: z.ZodOptional<z.ZodString>;
     placeholder: z.ZodOptional<z.ZodString>;
+    /**
+     * 후보 목록. `ref`(0.8.0)를 주면 렌더러가 행을 칩(아바타·이름·MXID)으로 그린다 —
+     * 🔴 `label` 은 평문 사본으로 남긴다(RefSchema 머리말).
+     * `hint`(0.9.0)는 라벨 아래 한 줄 보조 설명 — `radio` 의 같은 이름 키와 같은 뜻이다.
+     */
     options: z.ZodArray<z.ZodObject<{
         value: z.ZodString;
         label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }, {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
     multi: z.ZodOptional<z.ZodBoolean>;
+    /** 후보가 어디서 오나 (0.9.0). 생략 = `options` 배열. 위 `SelectSourceSchema` 머리말 참조. */
+    source: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        /** 이 방의 멤버가 후보다. 값은 MXID 배열이고, 이름·아바타는 클라가 방 상태로 해석한다. */
+        kind: z.ZodLiteral<"room">;
+        /** 보는 사람 자신을 후보에서 뺀다(기본 false). "받을 사람"처럼 나를 고를 일이 없는 자리. */
+        exclude_self: z.ZodOptional<z.ZodBoolean>;
+        /** 후보에서 뺄 MXID 목록 — 이미 담당인 사람, 퇴사 처리 중인 계정 등. */
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 봇·에이전트 계정도 후보에 넣는다(기본 false — 사람을 고르는 자리가 대부분이다). */
+        include_bots: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    }, {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    }>, z.ZodObject<{
+        /** 타이핑할 때마다 서버에 묻는다 — 답은 `org.corp.ui.action.result` 의 `kind: "options"`. */
+        kind: z.ZodLiteral<"query">;
+        /**
+         * 질의를 받을 액션. 클라는 `action_type: "query"` 로 `{ q, name }` 을 실어 보낸다.
+         * 🔴 사람이 누른 게 아니므로 앱은 **부작용 없이** `ctx.result({ kind: "options", name, options })`
+         * 로만 답해야 한다(같은 핸들러가 제출도 처리한다면 `action_type` 으로 갈라야 한다).
+         */
+        action_id: z.ZodString;
+        /** 몇 글자부터 묻나(기본 1). 한 글자에 전체 스캔이 도는 백엔드라면 올린다. */
+        min_chars: z.ZodOptional<z.ZodNumber>;
+        /** 타이핑이 멎고 몇 ms 뒤에 묻나(기본 300). */
+        debounce_ms: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    }, {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    }>]>>;
+    /**
+     * 표현 힌트 (0.9.0) — **능력이 아니라 룩이다.** 생략하면 렌더러가 후보 수·`multi`·`source` 로 고른다.
+     *  · `list`/`segmented` — `radio` 의 같은 이름 표현과 **같은 뜻**(펼친 목록 / 한 줄 세그먼트).
+     *    `multi` 와 같이 쓰면 그릴 수 있는 컨트롤이 없어 칩 콤보박스로 떨어진다.
+     *  · `dropdown` — 트리거 + 떠 있는 목록(콤보박스). 네이티브 `<select>` 가 아니다.
+     *  · `chips` — 고른 것이 트리거 안에서 칩으로 선다(`multi` 의 기본 표현).
+     */
+    style: z.ZodOptional<z.ZodEnum<["list", "segmented", "dropdown", "chips"]>>;
+    /**
+     * 목록 안 검색창 (0.9.0). 생략하면 렌더러가 켠다 — 후보가 8 개를 넘거나, 공급원이 방/질의일 때.
+     * 🔴 이건 "검색하기 **버튼**"이 아니다. 타이핑이 곧 필터이고, 왕복은 `source: query` 일 때만 돈다.
+     */
+    searchable: z.ZodOptional<z.ZodBoolean>;
+    /** 고르지 않으면 제출을 잠근다 (0.7.0). 🔴 UX 다, 진실은 서버. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * `multi: true` 전용 — **고른 개수**의 하한/상한 (0.7.0). 단일 선택에선 무시한다.
+     * (`input` 의 `min`/`max` 는 값의 크기라 문자열인데, 여기는 개수라 정수다.)
+     * 🔴 UX 다, 진실은 서버.
+     */
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    /** 제약 위반 시 보여 줄 작성자 소유 문장 (0.7.0). 없으면 렌더러 크롬 문구. */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }[];
     type: "select";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
     placeholder?: string | undefined;
+    required?: boolean | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    error?: string | undefined;
+    style?: "segmented" | "list" | "dropdown" | "chips" | undefined;
     multi?: boolean | undefined;
+    source?: {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    } | {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    } | undefined;
+    searchable?: boolean | undefined;
 }, {
     options: {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }[];
     type: "select";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
     placeholder?: string | undefined;
+    required?: boolean | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    error?: string | undefined;
+    style?: "segmented" | "list" | "dropdown" | "chips" | undefined;
     multi?: boolean | undefined;
+    source?: {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    } | {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    } | undefined;
+    searchable?: boolean | undefined;
 }>;
+export type SelectBlock = z.infer<typeof SelectBlockSchema>;
+/** 후보 한 줄 — `select.options[]` 와 `action.result` 의 `options[]` 가 같은 모양을 쓴다. */
+export type SelectOption = SelectBlock["options"][number];
 export declare const CheckboxBlockSchema: z.ZodObject<{
     type: z.ZodLiteral<"checkbox">;
     name: z.ZodString;
@@ -507,6 +970,36 @@ export declare const ButtonBlockSchema: z.ZodObject<{
      * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
      */
     hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * `hidden_for` 의 **짝**(0.7.0) — 이 MXID 들에게만 버튼을 보인다(화이트리스트).
+     *
+     * 왜 둘 다 있나: 두 축은 아는 것이 다르다. `hidden_for` 는 "이 사람은 절대 못 누른다"를 아는 경우고
+     * (자기 PR 자기 승인), `visible_for` 는 "이 사람만 누를 수 있다"를 아는 경우다(현재 수신자). 후자를
+     * `hidden_for` 로 쓰려면 방 멤버 전원을 열거해야 하고, 그 목록은 카드를 만든 **순간**에 굳는다 —
+     * 나중에 들어온 사람에게 버튼이 그냥 보인다.
+     *
+     * 🔴 **둘 다 있으면 `hidden_for` 가 이긴다.** "못 누른다"가 "누를 수 있다"보다 강한 진술이라서다
+     * (겹치는 경우는 보통 작성자의 실수이고, 그때 안전한 쪽은 감추는 쪽이다).
+     * 🔴 **권한이 아니다** — `hidden_for` 와 똑같이 UX 고, 진짜 게이트는 언제나 서버다.
+     *   이 키를 모르는 옛 클라는 strip 하고 **전원에게** 버튼을 보인다 → 누르면 서버가 거절한다.
+     */
+    visible_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * 버튼이 잠기거나 감춰진 **이유 한 줄**(0.7.0) — 사람이 읽을 문장(작성자 소유).
+     * `disabled` 면 버튼 옆 보조 텍스트로, `visible_for` 로 감춰졌으면 버튼 자리에 이 줄만 남는다.
+     * "눌러 봐야 안다"를 없애는 것이 요점이다. 🔴 UX 다, 진실은 서버.
+     */
+    disabled_reason: z.ZodOptional<z.ZodString>;
+    /**
+     * **중요도**(0.9.0) — 배치가 아니라 의도다. `"secondary"` 는 "이건 부차적이다"라는 말이고,
+     * 액션 줄이 좁아 한 줄에 못 들어갈 때 렌더러가 **먼저 ⋯ 메뉴로 접는** 대상이 된다.
+     *
+     * 🔴 **`style` 과 다른 축이다.** `style` 은 *생김새*(기본/강조/위험)이고 이것은 *중요도*다 —
+     * `style: "danger"` 인 "보고 취소"가 부차적일 수 있다(위험하지만 주 동작은 아니다). 둘을 한
+     * 축으로 묶으면 그 카드를 표현할 수 없다.
+     * ⚠️ 생략하면 지금과 **완전히 같다**(안 접힌다). 접기는 `"secondary"` 를 선언한 것에만 일어난다.
+     */
+    priority: z.ZodOptional<z.ZodEnum<["primary", "secondary"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "button";
     text: string;
@@ -521,6 +1014,9 @@ export declare const ButtonBlockSchema: z.ZodObject<{
     } | undefined;
     disabled?: boolean | undefined;
     hidden_for?: string[] | undefined;
+    visible_for?: string[] | undefined;
+    disabled_reason?: string | undefined;
+    priority?: "primary" | "secondary" | undefined;
 }, {
     type: "button";
     text: string;
@@ -535,6 +1031,9 @@ export declare const ButtonBlockSchema: z.ZodObject<{
     } | undefined;
     disabled?: boolean | undefined;
     hidden_for?: string[] | undefined;
+    visible_for?: string[] | undefined;
+    disabled_reason?: string | undefined;
+    priority?: "primary" | "secondary" | undefined;
 }>;
 export type ButtonBlock = z.infer<typeof ButtonBlockSchema>;
 /**
@@ -549,157 +1048,24 @@ export declare const LinkButtonBlockSchema: z.ZodObject<{
     style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
     /** 새 탭으로 열기(기본 true). */
     external: z.ZodOptional<z.ZodBoolean>;
+    /** 중요도 (0.9.0) — `ButtonBlockSchema.priority` 와 같은 뜻. 좁으면 ⋯ 로 접힌다. */
+    priority: z.ZodOptional<z.ZodEnum<["primary", "secondary"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "linkButton";
-    text: string;
     url: string;
+    text: string;
     style?: "danger" | "default" | "primary" | undefined;
+    priority?: "primary" | "secondary" | undefined;
     external?: boolean | undefined;
 }, {
     type: "linkButton";
-    text: string;
     url: string;
+    text: string;
     style?: "danger" | "default" | "primary" | undefined;
+    priority?: "primary" | "secondary" | undefined;
     external?: boolean | undefined;
 }>;
 export type LinkButtonBlock = z.infer<typeof LinkButtonBlockSchema>;
-/** 버튼 한 줄 묶음 — 액션 버튼(button)과 링크 버튼(linkButton)을 섞어 배치 가능. */
-export declare const ActionsBlockSchema: z.ZodObject<{
-    type: z.ZodLiteral<"actions">;
-    elements: z.ZodArray<z.ZodUnion<[z.ZodObject<{
-        type: z.ZodLiteral<"button">;
-        /** 어떤 액션인지 식별. 클릭 시 org.corp.ui.action.action_id 로 회신됨. */
-        action_id: z.ZodString;
-        text: z.ZodString;
-        style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
-        /** 버튼 고유 페이로드 (폼 값과 별개로 함께 전송) */
-        value: z.ZodOptional<z.ZodString>;
-        confirm: z.ZodOptional<z.ZodObject<{
-            title: z.ZodString;
-            text: z.ZodString;
-            ok: z.ZodOptional<z.ZodString>;
-            cancel: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        }, {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            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;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    }, {
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"linkButton">;
-        text: z.ZodString;
-        /** 이동할 https URL. 클라이언트가 출처를 검증(아니면 비활성 표시). */
-        url: z.ZodString;
-        style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
-        /** 새 탭으로 열기(기본 true). */
-        external: z.ZodOptional<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    }, {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    }>]>, "many">;
-}, "strip", z.ZodTypeAny, {
-    type: "actions";
-    elements: ({
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    } | {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    })[];
-}, {
-    type: "actions";
-    elements: ({
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    } | {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    })[];
-}>;
 /**
  * 오버플로 메뉴 — "⋯" 트리거를 누르면 액션 항목 목록이 팝오버로 열린다(공간 절약형 액션 묶음).
  * 각 항목은 button 과 동일하게 action_id 로 회신하고 confirm(파괴적 액션 확인)도 지원.
@@ -732,6 +1098,12 @@ export declare const OverflowBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         }>>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /** 이 MXID 들에게만 항목을 보인다 (0.7.0) — `ButtonBlockSchema.visible_for` 와 같은 규칙. 🔴 UX 다, 진실은 서버. */
+        visible_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 이 MXID 들에게 항목을 감춘다 (0.7.0) — 둘 다 있으면 이쪽이 이긴다(버튼과 같은 규칙). */
+        hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 잠기거나 감춰진 이유 한 줄 (0.7.0, 작성자 소유 문장). 🔴 UX 다, 진실은 서버. */
+        disabled_reason: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         text: string;
         action_id: string;
@@ -744,6 +1116,9 @@ export declare const OverflowBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }, {
         text: string;
         action_id: string;
@@ -756,6 +1131,9 @@ export declare const OverflowBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "overflow";
@@ -771,6 +1149,9 @@ export declare const OverflowBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }[];
     label?: string | undefined;
 }, {
@@ -787,10 +1168,45 @@ export declare const OverflowBlockSchema: z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }[];
     label?: string | undefined;
 }>;
 export type OverflowBlock = z.infer<typeof OverflowBlockSchema>;
+/**
+ * **액션 줄의 원소**(0.9.0 부터 셋) — 버튼 · 링크 버튼 · ⋯ 메뉴.
+ *
+ * 🔴 `overflow` 가 여기 들어온 이유는 배치다(감사 문서 D). 최상위 블록으로만 둘 수 있던 시절엔
+ * 세로 flex 인 `.cob-blocks` 안에서 **제 줄을 통째로 먹었다** — 버튼 넷 아래에 ⋯ 하나가 두 번째
+ * 줄에 혼자 서는 모양이다. 액션 줄 안으로 들어오면 그 줄의 끝에 선다.
+ *
+ * ⚠️ **옛 클라에는 이 원소가 안 보인다.** 유니온이 닫혀 있어 모르는 원소 하나가 배열 전체를
+ * 실패시키고 → `dropUnknownBlocks` 가 그 **actions 블록을 통째로** 떨군다(0.9.0 의
+ * `dropUnknownBlocks` 는 원소 단위로 거르지만 그건 *새* 클라 이야기다). 그래서 빌더
+ * (`card.actions`)가 전환기 동안 **최상위 `overflow` 사본**을 같이 낸다 — `card.activity` 의
+ * `legacy_for` 와 같은 규약이고, 새 렌더러는 사본을 알아보고 건너뛴다.
+ */
+/**
+ * 🔴 **타입을 손으로 적고 스키마에 주석을 단다** — `z.infer` 로 두면 TS 가 이 유니온을 통째로
+ * 펼치는데, `overflow` 가 들어오면서 그 펼친 타입이 `surfaces.ts` 의 `AppSurfaceContentSchema`
+ * (패널 → 서피스 바디 → 카드 → 블록 → 액션)까지 타고 올라가 **직렬화 한도를 넘는다**(TS7056).
+ * 주석 한 줄이 그 자리에서 추론을 끊는다. 값의 모양은 그대로다.
+ */
+export type ActionElement = ButtonBlock | LinkButtonBlock | OverflowBlock;
+export declare const ActionElementSchema: z.ZodType<ActionElement>;
+/** 버튼 한 줄 묶음 — 액션 버튼(button)·링크 버튼(linkButton)·⋯ 메뉴(overflow)를 섞어 배치 가능. */
+export declare const ActionsBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"actions">;
+    elements: z.ZodArray<z.ZodType<ActionElement, z.ZodTypeDef, ActionElement>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "actions";
+    elements: ActionElement[];
+}, {
+    type: "actions";
+    elements: ActionElement[];
+}>;
 /**
  * 진행률 바 (0~100). 에이전트가 m.replace 편집으로 갱신해 "스트리밍" 진행 표시 가능.
  *
@@ -822,25 +1238,25 @@ export declare const StepsBlockSchema: z.ZodObject<{
         note: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }, {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "steps";
     items: {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }[];
 }, {
     type: "steps";
     items: {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }[];
 }>;
@@ -1017,12 +1433,60 @@ export declare const AvatarBlockSchema: z.ZodObject<{
     initials: z.ZodOptional<z.ZodString>;
     src: z.ZodOptional<z.ZodString>;
     subtitle: z.ZodOptional<z.ZodString>;
+    /**
+     * 이 아바타가 가리키는 사람/엔티티 (0.8.0). 있으면 렌더러가 해석 결과(이름·사진)로 `name`/`src` 를
+     * **덮어쓴다** — 방 상태가 정답이라 개명·프로필 변경이 즉시 반영된다.
+     * 🔴 `name` 은 평문 사본으로 남긴다: 해석기가 없거나(외부 임베더) 옛 클라면 그 문자열이 유일한 답이다.
+     */
+    ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+        user: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        user: string;
+    }, {
+        user: string;
+    }>, z.ZodObject<{
+        /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+        entity: z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            id: string;
+        }, {
+            type: string;
+            id: string;
+        }>;
+        /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    }, {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    }>]>>;
     /** 우하단 상태점 — 네 상태가 각자 색을 갖는다(`--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;
+    ref?: {
+        user: string;
+    } | {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    } | undefined;
     initials?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
@@ -1030,6 +1494,15 @@ export declare const AvatarBlockSchema: z.ZodObject<{
     type: "avatar";
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
+    ref?: {
+        user: string;
+    } | {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    } | undefined;
     initials?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
@@ -1163,15 +1636,15 @@ export declare const EntityRefBlockSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "entityRef";
     label: string;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
-    url?: string | undefined;
     entity?: string | undefined;
+    url?: string | undefined;
+    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }, {
     type: "entityRef";
     label: string;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
-    url?: string | undefined;
     entity?: string | undefined;
+    url?: string | undefined;
+    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }>;
 export type EntityRefBlock = z.infer<typeof EntityRefBlockSchema>;
 /**
@@ -1202,8 +1675,8 @@ export declare const KanbanBlockSchema: z.ZodObject<{
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             }>>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1211,8 +1684,8 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }, {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1221,10 +1694,11 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             meta?: string[] | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1232,13 +1706,13 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }, {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1246,17 +1720,17 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }>, "many">;
     caption: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "kanban";
     columns: {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1264,17 +1738,17 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
 }, {
     type: "kanban";
     columns: {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1282,7 +1756,6 @@ export declare const KanbanBlockSchema: z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1327,6 +1800,27 @@ export declare const CollapsibleBlockSchema: z.ZodObject<{
     /** 처음부터 펼쳐둘지(기본 접힘). */
     open: z.ZodOptional<z.ZodBoolean>;
     tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+    /**
+     * **옛 클라용 사본이라는 표식**(0.8.0). 빌더가 새 블록을 낼 때 같은 내용을 이 접기 블록으로 병기하고
+     * 여기에 원본 블록 타입을 적는다.
+     *
+     * 왜 필요한가: 새 *블록 타입*은 `dropUnknownBlocks` 에서 **통째로 떨어진다**(키 추가와 달리 degrade
+     * 경로가 없다). 그래서 `activity` 는 빌더가 사본을 같이 내고, **새 렌더러는 원본을 아니까 사본을
+     * 안 그린다** — 안 그러면 새 클라에서 같은 이력이 두 번 보인다.
+     * 이 키를 모르는 옛 클라는 strip 하고 평범한 접기 블록으로 그린다(그게 목적이다).
+     *
+     * 전환기가 끝나 클라 배포가 충분히 퍼지면 빌더의 `legacy` 기본값을 false 로 바꾼다(이 시리즈 밖).
+     */
+    legacy_for: z.ZodOptional<z.ZodEnum<["activity"]>>;
+    /**
+     * **접힌 채로도 보이는 한 줄**(0.9.0) — 제목 오른쪽에 흐리게 선다. 펼치면 숨는다(본문이 답이다).
+     *
+     * 왜 필요한가(감사 문서 D): 접기는 "카드 높이를 안 먹는 상세"인데, 지금은 접힌 상태에서 **정보가
+     * 0** 이라 사용자가 펼쳐 봐야 안에 뭐가 있는지 안다. 마지막 한 줄만 보여 주면 대개 펼칠 필요가 없다
+     * ("마지막: 희태 박에게 전달 · 6:12").
+     * ⚠️ 본문의 요약이지 본문의 **대체**가 아니다 — 여기만 읽고 끝나도 되는 내용이면 접지 말 것.
+     */
+    summary: z.ZodOptional<z.ZodString>;
     /**
      * 펼치면 보이는 중첩 블록(재귀). 런타임은 z.lazy 로 BlockSchema 를 지연 참조해 재귀 검증하지만,
      * 정적 타입은 z.ZodTypeAny 로 끊는다 — Block 이 z.infer 기반이라 재귀 타입 별칭이 conditional type
@@ -1339,20 +1833,220 @@ export declare const CollapsibleBlockSchema: z.ZodObject<{
     blocks: any[];
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     open?: boolean | undefined;
+    legacy_for?: "activity" | undefined;
+    summary?: string | undefined;
 }, {
     type: "collapsible";
     title: string;
     blocks: any[];
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     open?: boolean | undefined;
+    legacy_for?: "activity" | undefined;
+    summary?: string | undefined;
 }>;
 export type CollapsibleBlock = {
     type: "collapsible";
     title: string;
     open?: boolean;
     tone?: Tone;
+    legacy_for?: "activity";
+    summary?: string;
     blocks: Block[];
 };
+/**
+ * **처리 이력**(0.8.0) — 참조가 주어인 시간순 목록. 이 시리즈의 **유일한 새 블록**이다.
+ *
+ * 왜 블록인가(감사 문서 C): "누가 · 무엇을 · 언제"는 지금 `collapsible` 안의 마크다운 텍스트로 산다.
+ * 그래서 접힌 상태에선 정보가 0이고, 펼쳐도 사람·시각에 구조가 없어 아바타도 상대 시각도 못 붙는다.
+ * 기존 블록의 새 축으로는 표현할 수 없는 모양이라("주어가 참조인 행의 목록") 블록이 정당하다.
+ *
+ * 🔴 **새 블록은 `dropUnknownBlocks` 에서 통째로 떨어진다** — 키 추가와 달리 degrade 경로가 없다.
+ * 그래서 빌더(`card.activity`)가 옛 클라용 `collapsible` 사본을 **같이** 낸다(`legacy_for: "activity"`).
+ *
+ * 항목은 **최신순**이다(맨 앞이 가장 최근). `maxVisible` 을 넘는 나머지는 렌더러가 접는다.
+ */
+export declare const ActivityBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"activity">;
+    label: z.ZodOptional<z.ZodString>;
+    /** 펼쳐 둘 최근 항목 수(기본 3). 나머지는 "이전 N건 더 보기"로 접힌다. */
+    maxVisible: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodArray<z.ZodObject<{
+        /** 행위의 주어 — 참조면 아바타·이름으로, 문자열이면 그대로. */
+        who: z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>]>;
+        /** 무엇을 했나 — 인라인 마크다운 허용(`text` 블록의 인라인 규칙과 같다). */
+        what: z.ZodString;
+        /** 언제 — ISO 8601 타임스탬프 문자열. 렌더러가 상대 시각으로 그린다. */
+        at: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+        /** 대상(선택) — "A 가 **B 에게** 전달" 의 B. */
+        to: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>]>>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }, {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "activity";
+    items: {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }[];
+    label?: string | undefined;
+    maxVisible?: number | undefined;
+}, {
+    type: "activity";
+    items: {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }[];
+    label?: string | undefined;
+    maxVisible?: number | undefined;
+}>;
+export type ActivityBlock = z.infer<typeof ActivityBlockSchema>;
 /**
  * 탈출구(escape hatch): A2UI/UI Blocks로 표현하기 어려운 무거운 UI(차트·대형 그리드·지도)는
  * Matrix Widget으로. 클라이언트가 신뢰 경계 안에서 sandboxed iframe으로 렌더한다.
@@ -1449,6 +2143,54 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }>, "many">>;
+        /**
+         * 이 값이 가리키는 사람/엔티티 (0.8.0). 있으면 렌더러가 칩(아바타+이름 / 종류+라벨)으로 그린다.
+         * 🔴 **`value` 는 평문 사본으로 남긴다** — `parts` 와 같은 규칙이다(RefSchema 머리말).
+         */
+        ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>>;
+        /**
+         * **이 항목은 문단이다**(0.9.0) — 값이 아니라 본문. 전체폭으로 서고 값 서체(600)를 풀며
+         * 인라인 마크다운을 그린다.
+         *
+         * 왜 필요한가(감사 문서 D): "막힌 일: ㅁㄴㄹ…" 같은 자유 서술이 지금은 굵은 값 서체로 서서
+         * 숫자·상태와 같은 무게로 읽힌다. 작성자가 `short` 로 열 수를 강제하던 것과 같은 자리 —
+         * 작성자는 "이건 문단이다"만 말하고 폭·서체는 렌더러가 정한다.
+         * ⚠️ `short` 와 같이 주면 `long` 이 이긴다(반폭 문단은 없다).
+         */
+        long: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
@@ -1457,6 +2199,16 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }, {
         value: string;
         label: string;
@@ -1465,7 +2217,26 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }>, "many">;
+    /**
+     * 열 수 **명시 오버라이드**(0.9.0). 생략이 기본이고, 기본은 폭이 정하는 auto-fit 이다
+     * (그리고 `short` 넷이면 2×2 로 묶인다 — 0.7.0 에서 이미 들어간 규칙).
+     *
+     * 🔴 **기본을 되돌리지 않는다.** 이 키는 auto-fit 이 틀리는 드문 경우(라벨이 길어 3열이 찢어지는
+     * 표 같은 fields)를 위한 탈출구다 — 늘 주면 좁은 화면에서 열이 안 줄어 값이 짜부라진다.
+     * `"auto"` 는 명시적으로 기본을 고르는 값이다(작성자가 "여긴 렌더러에 맡긴다"를 적을 수 있게).
+     */
+    columns: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<"auto">]>>;
 }, "strip", z.ZodTypeAny, {
     type: "fields";
     items: {
@@ -1476,7 +2247,18 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }[];
+    columns?: 2 | 3 | "auto" | undefined;
 }, {
     type: "fields";
     items: {
@@ -1487,7 +2269,18 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             text: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
         }[] | undefined;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        long?: boolean | undefined;
     }[];
+    columns?: 2 | 3 | "auto" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"image">;
     /** https URL 또는 mxc:// (둘 중 하나 권장). 클라이언트가 출처를 검증한다. */
@@ -1506,7 +2299,6 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     alt?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"context">;
-    /** 작은 보조 텍스트/아이콘 줄 */
     elements: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         icon: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -1579,25 +2371,25 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         note: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }, {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "steps";
     items: {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }[];
 }, {
     type: "steps";
     items: {
         label: string;
-        status?: "done" | "active" | "todo" | "error" | undefined;
+        status?: "error" | "done" | "active" | "todo" | undefined;
         note?: string | undefined;
     }[];
 }>, z.ZodObject<{
@@ -1674,12 +2466,60 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     initials: z.ZodOptional<z.ZodString>;
     src: z.ZodOptional<z.ZodString>;
     subtitle: z.ZodOptional<z.ZodString>;
+    /**
+     * 이 아바타가 가리키는 사람/엔티티 (0.8.0). 있으면 렌더러가 해석 결과(이름·사진)로 `name`/`src` 를
+     * **덮어쓴다** — 방 상태가 정답이라 개명·프로필 변경이 즉시 반영된다.
+     * 🔴 `name` 은 평문 사본으로 남긴다: 해석기가 없거나(외부 임베더) 옛 클라면 그 문자열이 유일한 답이다.
+     */
+    ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+        user: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        user: string;
+    }, {
+        user: string;
+    }>, z.ZodObject<{
+        /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+        entity: z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            id: string;
+        }, {
+            type: string;
+            id: string;
+        }>;
+        /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    }, {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    }>]>>;
     /** 우하단 상태점 — 네 상태가 각자 색을 갖는다(`--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;
+    ref?: {
+        user: string;
+    } | {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    } | undefined;
     initials?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
@@ -1687,6 +2527,15 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "avatar";
     name: string;
     status?: "online" | "away" | "busy" | "offline" | undefined;
+    ref?: {
+        user: string;
+    } | {
+        entity: {
+            type: string;
+            id: string;
+        };
+        url?: string | undefined;
+    } | undefined;
     initials?: string | undefined;
     src?: string | undefined;
     subtitle?: string | undefined;
@@ -1805,15 +2654,15 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "entityRef";
     label: string;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
-    url?: string | undefined;
     entity?: string | undefined;
+    url?: string | undefined;
+    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }, {
     type: "entityRef";
     label: string;
-    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
-    url?: string | undefined;
     entity?: string | undefined;
+    url?: string | undefined;
+    tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"kanban">;
     columns: z.ZodArray<z.ZodObject<{
@@ -1837,8 +2686,8 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
                 tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             }>>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1846,8 +2695,8 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }, {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1856,10 +2705,11 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             meta?: string[] | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1867,13 +2717,13 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }, {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1881,17 +2731,17 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }>, "many">;
     caption: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "kanban";
     columns: {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1899,17 +2749,17 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
 }, {
     type: "kanban";
     columns: {
+        id: string;
         title: string;
         cards: {
-            title: string;
             id: string;
+            title: string;
             tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
             badge?: {
                 label: string;
@@ -1917,7 +2767,6 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             } | undefined;
             meta?: string[] | undefined;
         }[];
-        id: string;
         tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     }[];
     caption?: string | undefined;
@@ -1941,6 +2790,186 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     label?: string | undefined;
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     expiredText?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"activity">;
+    label: z.ZodOptional<z.ZodString>;
+    /** 펼쳐 둘 최근 항목 수(기본 3). 나머지는 "이전 N건 더 보기"로 접힌다. */
+    maxVisible: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodArray<z.ZodObject<{
+        /** 행위의 주어 — 참조면 아바타·이름으로, 문자열이면 그대로. */
+        who: z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>]>;
+        /** 무엇을 했나 — 인라인 마크다운 허용(`text` 블록의 인라인 규칙과 같다). */
+        what: z.ZodString;
+        /** 언제 — ISO 8601 타임스탬프 문자열. 렌더러가 상대 시각으로 그린다. */
+        at: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+        /** 대상(선택) — "A 가 **B 에게** 전달" 의 B. */
+        to: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>]>>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }, {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "activity";
+    items: {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }[];
+    label?: string | undefined;
+    maxVisible?: number | undefined;
+}, {
+    type: "activity";
+    items: {
+        at: string;
+        who: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        };
+        what: string;
+        tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
+        to?: string | {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+    }[];
+    label?: string | undefined;
+    maxVisible?: number | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"code">;
     code: z.ZodString;
@@ -2011,6 +3040,27 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     /** 처음부터 펼쳐둘지(기본 접힘). */
     open: z.ZodOptional<z.ZodBoolean>;
     tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "danger", "info"]>>;
+    /**
+     * **옛 클라용 사본이라는 표식**(0.8.0). 빌더가 새 블록을 낼 때 같은 내용을 이 접기 블록으로 병기하고
+     * 여기에 원본 블록 타입을 적는다.
+     *
+     * 왜 필요한가: 새 *블록 타입*은 `dropUnknownBlocks` 에서 **통째로 떨어진다**(키 추가와 달리 degrade
+     * 경로가 없다). 그래서 `activity` 는 빌더가 사본을 같이 내고, **새 렌더러는 원본을 아니까 사본을
+     * 안 그린다** — 안 그러면 새 클라에서 같은 이력이 두 번 보인다.
+     * 이 키를 모르는 옛 클라는 strip 하고 평범한 접기 블록으로 그린다(그게 목적이다).
+     *
+     * 전환기가 끝나 클라 배포가 충분히 퍼지면 빌더의 `legacy` 기본값을 false 로 바꾼다(이 시리즈 밖).
+     */
+    legacy_for: z.ZodOptional<z.ZodEnum<["activity"]>>;
+    /**
+     * **접힌 채로도 보이는 한 줄**(0.9.0) — 제목 오른쪽에 흐리게 선다. 펼치면 숨는다(본문이 답이다).
+     *
+     * 왜 필요한가(감사 문서 D): 접기는 "카드 높이를 안 먹는 상세"인데, 지금은 접힌 상태에서 **정보가
+     * 0** 이라 사용자가 펼쳐 봐야 안에 뭐가 있는지 안다. 마지막 한 줄만 보여 주면 대개 펼칠 필요가 없다
+     * ("마지막: 희태 박에게 전달 · 6:12").
+     * ⚠️ 본문의 요약이지 본문의 **대체**가 아니다 — 여기만 읽고 끝나도 되는 내용이면 접지 말 것.
+     */
+    summary: z.ZodOptional<z.ZodString>;
     /**
      * 펼치면 보이는 중첩 블록(재귀). 런타임은 z.lazy 로 BlockSchema 를 지연 참조해 재귀 검증하지만,
      * 정적 타입은 z.ZodTypeAny 로 끊는다 — Block 이 z.infer 기반이라 재귀 타입 별칭이 conditional type
@@ -2023,12 +3073,16 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     blocks: any[];
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     open?: boolean | undefined;
+    legacy_for?: "activity" | undefined;
+    summary?: string | undefined;
 }, {
     type: "collapsible";
     title: string;
     blocks: any[];
     tone?: "neutral" | "success" | "warning" | "danger" | "info" | undefined;
     open?: boolean | undefined;
+    legacy_for?: "activity" | undefined;
+    summary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"widget">;
     url: z.ZodString;
@@ -2075,26 +3129,68 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
      * 단일 업로드로 동작한다(기능 축소일 뿐 파손 없음).
      */
     multiple: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 하한/상한 (0.7.0) — number/date/datetime/time 공용. **문자열**이다: 날짜·시각은 그 타입의 값
+     * 형식(`2026-09-22`·`18:15`)이고, number 면 숫자를 적은 문자열이다(와이어 canonical JSON 은
+     * 소수를 허용하지 않아 숫자 축을 열 수 없다 — `slider` 가 int 만 받는 것과 같은 제약).
+     *
+     * `"today"` 리터럴을 허용한다 — "기한은 오늘 이후"는 카드를 **보낸 날**이 아니라 **보는 날** 기준이라야
+     * 맞다(카드는 타임라인에 남고 며칠 뒤에도 눌린다). 렌더러가 그릴 때 해석한다.
+     *
+     * 🔴 **UX 다, 진실은 서버**(`hidden_for` 와 같은 자세). 클라가 미리 잠그는 건 헛걸음을 줄이려는
+     * 것뿐이고, 진짜 판정은 언제나 핸들러·게이트가 한다. 이 키를 모르는 옛 클라는 strip 하고 지금처럼
+     * 아무 제약 없이 제출한다 — 그러면 서버가 사람이 읽을 이유와 함께 거절한다(`action.result`).
+     */
+    min: z.ZodOptional<z.ZodString>;
+    max: z.ZodOptional<z.ZodString>;
+    /** 글자 수 하한/상한 (0.7.0) — 텍스트 계열 전용. 🔴 UX 다, 진실은 서버. */
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    /**
+     * 값이 맞아야 하는 정규식 **소스**(0.7.0, 예: `"^[A-Z]{2}-\\d{4}$"`). 플래그·구분자 없이 패턴만 적는다.
+     *
+     * 🔴 렌더러는 `new RegExp` 를 **try/catch 로 감싼다** — 작성자가 자바스크립트가 아닌 방언(파이썬
+     * `(?P<x>…)` 등)을 보내면 던지는데, 그걸로 카드 전체가 죽으면 안 된다. 못 읽는 패턴은 무시한다
+     * (= 제약 없음). 진짜 판정은 여전히 서버다.
+     */
+    pattern: z.ZodOptional<z.ZodString>;
+    /**
+     * 제약 위반 시 보여 줄 **작성자 소유 문장**(0.7.0). 없으면 렌더러 크롬 문구를 쓴다
+     * (`LabelContext` — "누구의 문자열인가"가 경계선이고, 도메인 사정을 아는 문장은 작성자 것이다).
+     */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "input";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
-    input?: "number" | "text" | "date" | "url" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
+    input?: "number" | "date" | "url" | "text" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
     placeholder?: string | undefined;
     required?: boolean | undefined;
     accept?: string | undefined;
     multiple?: boolean | undefined;
+    min?: string | undefined;
+    max?: string | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    pattern?: string | undefined;
+    error?: string | undefined;
 }, {
     type: "input";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
-    input?: "number" | "text" | "date" | "url" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
+    input?: "number" | "date" | "url" | "text" | "textarea" | "datetime" | "time" | "email" | "file" | undefined;
     placeholder?: string | undefined;
     required?: boolean | undefined;
     accept?: string | undefined;
     multiple?: boolean | undefined;
+    min?: string | undefined;
+    max?: string | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    pattern?: string | undefined;
+    error?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"toggle">;
     name: z.ZodString;
@@ -2167,6 +3263,10 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
     style: z.ZodOptional<z.ZodEnum<["cards", "segmented"]>>;
+    /** 고르지 않으면 제출을 잠근다 (0.7.0). 🔴 UX 다, 진실은 서버 — `input.required` 와 같은 자세. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /** 미선택 시 보여 줄 작성자 소유 문장 (0.7.0). 없으면 렌더러 크롬 문구. */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
@@ -2177,6 +3277,8 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    required?: boolean | undefined;
+    error?: string | undefined;
     style?: "cards" | "segmented" | undefined;
 }, {
     options: {
@@ -2188,46 +3290,230 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     name: string;
     value?: string | undefined;
     label?: string | undefined;
+    required?: boolean | undefined;
+    error?: string | undefined;
     style?: "cards" | "segmented" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"select">;
     name: z.ZodString;
     label: z.ZodOptional<z.ZodString>;
     placeholder: z.ZodOptional<z.ZodString>;
+    /**
+     * 후보 목록. `ref`(0.8.0)를 주면 렌더러가 행을 칩(아바타·이름·MXID)으로 그린다 —
+     * 🔴 `label` 은 평문 사본으로 남긴다(RefSchema 머리말).
+     * `hint`(0.9.0)는 라벨 아래 한 줄 보조 설명 — `radio` 의 같은 이름 키와 같은 뜻이다.
+     */
     options: z.ZodArray<z.ZodObject<{
         value: z.ZodString;
         label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            /** Matrix 사용자 id — `@local:server` 형태. 해석(이름·아바타)은 호스트가 주입한다(PeopleProvider). */
+            user: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            user: string;
+        }, {
+            user: string;
+        }>, z.ZodObject<{
+            /** 도메인 엔티티 — `entityRef` **블록**이 이미 쓰는 종류/식별자 짝이 값 안으로 들어온 것. */
+            entity: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                id: string;
+            }, {
+                type: string;
+                id: string;
+            }>;
+            /** 클릭 시 이동할 https URL(선택). 출처는 클라가 검증한다. */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }, {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        }>]>>;
     }, "strip", z.ZodTypeAny, {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }, {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }>, "many">;
     value: z.ZodOptional<z.ZodString>;
     multi: z.ZodOptional<z.ZodBoolean>;
+    /** 후보가 어디서 오나 (0.9.0). 생략 = `options` 배열. 위 `SelectSourceSchema` 머리말 참조. */
+    source: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        /** 이 방의 멤버가 후보다. 값은 MXID 배열이고, 이름·아바타는 클라가 방 상태로 해석한다. */
+        kind: z.ZodLiteral<"room">;
+        /** 보는 사람 자신을 후보에서 뺀다(기본 false). "받을 사람"처럼 나를 고를 일이 없는 자리. */
+        exclude_self: z.ZodOptional<z.ZodBoolean>;
+        /** 후보에서 뺄 MXID 목록 — 이미 담당인 사람, 퇴사 처리 중인 계정 등. */
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 봇·에이전트 계정도 후보에 넣는다(기본 false — 사람을 고르는 자리가 대부분이다). */
+        include_bots: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    }, {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    }>, z.ZodObject<{
+        /** 타이핑할 때마다 서버에 묻는다 — 답은 `org.corp.ui.action.result` 의 `kind: "options"`. */
+        kind: z.ZodLiteral<"query">;
+        /**
+         * 질의를 받을 액션. 클라는 `action_type: "query"` 로 `{ q, name }` 을 실어 보낸다.
+         * 🔴 사람이 누른 게 아니므로 앱은 **부작용 없이** `ctx.result({ kind: "options", name, options })`
+         * 로만 답해야 한다(같은 핸들러가 제출도 처리한다면 `action_type` 으로 갈라야 한다).
+         */
+        action_id: z.ZodString;
+        /** 몇 글자부터 묻나(기본 1). 한 글자에 전체 스캔이 도는 백엔드라면 올린다. */
+        min_chars: z.ZodOptional<z.ZodNumber>;
+        /** 타이핑이 멎고 몇 ms 뒤에 묻나(기본 300). */
+        debounce_ms: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    }, {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    }>]>>;
+    /**
+     * 표현 힌트 (0.9.0) — **능력이 아니라 룩이다.** 생략하면 렌더러가 후보 수·`multi`·`source` 로 고른다.
+     *  · `list`/`segmented` — `radio` 의 같은 이름 표현과 **같은 뜻**(펼친 목록 / 한 줄 세그먼트).
+     *    `multi` 와 같이 쓰면 그릴 수 있는 컨트롤이 없어 칩 콤보박스로 떨어진다.
+     *  · `dropdown` — 트리거 + 떠 있는 목록(콤보박스). 네이티브 `<select>` 가 아니다.
+     *  · `chips` — 고른 것이 트리거 안에서 칩으로 선다(`multi` 의 기본 표현).
+     */
+    style: z.ZodOptional<z.ZodEnum<["list", "segmented", "dropdown", "chips"]>>;
+    /**
+     * 목록 안 검색창 (0.9.0). 생략하면 렌더러가 켠다 — 후보가 8 개를 넘거나, 공급원이 방/질의일 때.
+     * 🔴 이건 "검색하기 **버튼**"이 아니다. 타이핑이 곧 필터이고, 왕복은 `source: query` 일 때만 돈다.
+     */
+    searchable: z.ZodOptional<z.ZodBoolean>;
+    /** 고르지 않으면 제출을 잠근다 (0.7.0). 🔴 UX 다, 진실은 서버. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * `multi: true` 전용 — **고른 개수**의 하한/상한 (0.7.0). 단일 선택에선 무시한다.
+     * (`input` 의 `min`/`max` 는 값의 크기라 문자열인데, 여기는 개수라 정수다.)
+     * 🔴 UX 다, 진실은 서버.
+     */
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    /** 제약 위반 시 보여 줄 작성자 소유 문장 (0.7.0). 없으면 렌더러 크롬 문구. */
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     options: {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }[];
     type: "select";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
     placeholder?: string | undefined;
+    required?: boolean | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    error?: string | undefined;
+    style?: "segmented" | "list" | "dropdown" | "chips" | undefined;
     multi?: boolean | undefined;
+    source?: {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    } | {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    } | undefined;
+    searchable?: boolean | undefined;
 }, {
     options: {
         value: string;
         label: string;
+        ref?: {
+            user: string;
+        } | {
+            entity: {
+                type: string;
+                id: string;
+            };
+            url?: string | undefined;
+        } | undefined;
+        hint?: string | undefined;
     }[];
     type: "select";
     name: string;
     value?: string | undefined;
     label?: string | undefined;
     placeholder?: string | undefined;
+    required?: boolean | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    error?: string | undefined;
+    style?: "segmented" | "list" | "dropdown" | "chips" | undefined;
     multi?: boolean | undefined;
+    source?: {
+        kind: "room";
+        exclude_self?: boolean | undefined;
+        exclude?: string[] | undefined;
+        include_bots?: boolean | undefined;
+    } | {
+        kind: "query";
+        action_id: string;
+        min_chars?: number | undefined;
+        debounce_ms?: number | undefined;
+    } | undefined;
+    searchable?: boolean | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"checkbox">;
     name: z.ZodString;
@@ -2311,6 +3597,36 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
      * 보여 줘도 안전하다(누르면 서버가 사람이 읽을 이유와 함께 거절한다).
      */
     hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * `hidden_for` 의 **짝**(0.7.0) — 이 MXID 들에게만 버튼을 보인다(화이트리스트).
+     *
+     * 왜 둘 다 있나: 두 축은 아는 것이 다르다. `hidden_for` 는 "이 사람은 절대 못 누른다"를 아는 경우고
+     * (자기 PR 자기 승인), `visible_for` 는 "이 사람만 누를 수 있다"를 아는 경우다(현재 수신자). 후자를
+     * `hidden_for` 로 쓰려면 방 멤버 전원을 열거해야 하고, 그 목록은 카드를 만든 **순간**에 굳는다 —
+     * 나중에 들어온 사람에게 버튼이 그냥 보인다.
+     *
+     * 🔴 **둘 다 있으면 `hidden_for` 가 이긴다.** "못 누른다"가 "누를 수 있다"보다 강한 진술이라서다
+     * (겹치는 경우는 보통 작성자의 실수이고, 그때 안전한 쪽은 감추는 쪽이다).
+     * 🔴 **권한이 아니다** — `hidden_for` 와 똑같이 UX 고, 진짜 게이트는 언제나 서버다.
+     *   이 키를 모르는 옛 클라는 strip 하고 **전원에게** 버튼을 보인다 → 누르면 서버가 거절한다.
+     */
+    visible_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * 버튼이 잠기거나 감춰진 **이유 한 줄**(0.7.0) — 사람이 읽을 문장(작성자 소유).
+     * `disabled` 면 버튼 옆 보조 텍스트로, `visible_for` 로 감춰졌으면 버튼 자리에 이 줄만 남는다.
+     * "눌러 봐야 안다"를 없애는 것이 요점이다. 🔴 UX 다, 진실은 서버.
+     */
+    disabled_reason: z.ZodOptional<z.ZodString>;
+    /**
+     * **중요도**(0.9.0) — 배치가 아니라 의도다. `"secondary"` 는 "이건 부차적이다"라는 말이고,
+     * 액션 줄이 좁아 한 줄에 못 들어갈 때 렌더러가 **먼저 ⋯ 메뉴로 접는** 대상이 된다.
+     *
+     * 🔴 **`style` 과 다른 축이다.** `style` 은 *생김새*(기본/강조/위험)이고 이것은 *중요도*다 —
+     * `style: "danger"` 인 "보고 취소"가 부차적일 수 있다(위험하지만 주 동작은 아니다). 둘을 한
+     * 축으로 묶으면 그 카드를 표현할 수 없다.
+     * ⚠️ 생략하면 지금과 **완전히 같다**(안 접힌다). 접기는 `"secondary"` 를 선언한 것에만 일어난다.
+     */
+    priority: z.ZodOptional<z.ZodEnum<["primary", "secondary"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "button";
     text: string;
@@ -2325,6 +3641,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
     disabled?: boolean | undefined;
     hidden_for?: string[] | undefined;
+    visible_for?: string[] | undefined;
+    disabled_reason?: string | undefined;
+    priority?: "primary" | "secondary" | undefined;
 }, {
     type: "button";
     text: string;
@@ -2339,6 +3658,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
     disabled?: boolean | undefined;
     hidden_for?: string[] | undefined;
+    visible_for?: string[] | undefined;
+    disabled_reason?: string | undefined;
+    priority?: "primary" | "secondary" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"linkButton">;
     text: z.ZodString;
@@ -2347,153 +3669,31 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
     /** 새 탭으로 열기(기본 true). */
     external: z.ZodOptional<z.ZodBoolean>;
+    /** 중요도 (0.9.0) — `ButtonBlockSchema.priority` 와 같은 뜻. 좁으면 ⋯ 로 접힌다. */
+    priority: z.ZodOptional<z.ZodEnum<["primary", "secondary"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "linkButton";
-    text: string;
     url: string;
+    text: string;
     style?: "danger" | "default" | "primary" | undefined;
+    priority?: "primary" | "secondary" | undefined;
     external?: boolean | undefined;
 }, {
     type: "linkButton";
-    text: string;
     url: string;
+    text: string;
     style?: "danger" | "default" | "primary" | undefined;
+    priority?: "primary" | "secondary" | undefined;
     external?: boolean | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"actions">;
-    elements: z.ZodArray<z.ZodUnion<[z.ZodObject<{
-        type: z.ZodLiteral<"button">;
-        /** 어떤 액션인지 식별. 클릭 시 org.corp.ui.action.action_id 로 회신됨. */
-        action_id: z.ZodString;
-        text: z.ZodString;
-        style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
-        /** 버튼 고유 페이로드 (폼 값과 별개로 함께 전송) */
-        value: z.ZodOptional<z.ZodString>;
-        confirm: z.ZodOptional<z.ZodObject<{
-            title: z.ZodString;
-            text: z.ZodString;
-            ok: z.ZodOptional<z.ZodString>;
-            cancel: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        }, {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            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;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    }, {
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"linkButton">;
-        text: z.ZodString;
-        /** 이동할 https URL. 클라이언트가 출처를 검증(아니면 비활성 표시). */
-        url: z.ZodString;
-        style: z.ZodOptional<z.ZodEnum<["default", "primary", "danger"]>>;
-        /** 새 탭으로 열기(기본 true). */
-        external: z.ZodOptional<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    }, {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    }>]>, "many">;
+    elements: z.ZodArray<z.ZodType<ActionElement, z.ZodTypeDef, ActionElement>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "actions";
-    elements: ({
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    } | {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    })[];
+    elements: ActionElement[];
 }, {
     type: "actions";
-    elements: ({
-        type: "button";
-        text: string;
-        action_id: string;
-        value?: string | undefined;
-        style?: "danger" | "default" | "primary" | undefined;
-        confirm?: {
-            title: string;
-            text: string;
-            ok?: string | undefined;
-            cancel?: string | undefined;
-        } | undefined;
-        disabled?: boolean | undefined;
-        hidden_for?: string[] | undefined;
-    } | {
-        type: "linkButton";
-        text: string;
-        url: string;
-        style?: "danger" | "default" | "primary" | undefined;
-        external?: boolean | undefined;
-    })[];
+    elements: ActionElement[];
 }>, z.ZodObject<{
     type: z.ZodLiteral<"overflow">;
     /** 트리거 접근성 라벨(기본 "More actions"). */
@@ -2521,6 +3721,12 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         }>>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /** 이 MXID 들에게만 항목을 보인다 (0.7.0) — `ButtonBlockSchema.visible_for` 와 같은 규칙. 🔴 UX 다, 진실은 서버. */
+        visible_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 이 MXID 들에게 항목을 감춘다 (0.7.0) — 둘 다 있으면 이쪽이 이긴다(버튼과 같은 규칙). */
+        hidden_for: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** 잠기거나 감춰진 이유 한 줄 (0.7.0, 작성자 소유 문장). 🔴 UX 다, 진실은 서버. */
+        disabled_reason: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         text: string;
         action_id: string;
@@ -2533,6 +3739,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }, {
         text: string;
         action_id: string;
@@ -2545,6 +3754,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "overflow";
@@ -2560,6 +3772,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }[];
     label?: string | undefined;
 }, {
@@ -2576,6 +3791,9 @@ export declare const BlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             cancel?: string | undefined;
         } | undefined;
         disabled?: boolean | undefined;
+        hidden_for?: string[] | undefined;
+        visible_for?: string[] | undefined;
+        disabled_reason?: string | undefined;
     }[];
     label?: string | undefined;
 }>]>;