@underdogai/mesh-event-schemas 0.1.0

package/src/templates.ts

@@ -0,0 +1,736 @@
+/**
+ * Composite 템플릿 — 프리미티브 블록을 조합한 고수준 카드 빌더 (작성자 DX).
+ *
+ * 작성자는 매번 블록 트리를 손으로 쌓지 않고 templates.approval(...) 처럼 의도 단위로 만든다.
+ * registerTemplate() 로 작성자가 자기 템플릿을 등록할 수도 있다(클라이언트 릴리스 불필요 —
+ * 템플릿은 프리미티브로 "확장"되어 기존 렌더러가 그대로 그린다).
+ */
+import { buildUiCardContent, type TaskStatus, type TaskSummary, type UiCardContent } from "./events.js";
+import type { Block, ButtonStyle, Tone } from "./blocks.js";
+
+export type Template<P = unknown> = (params: P) => UiCardContent;
+
+const templateRegistry = new Map<string, Template>();
+
+export function registerTemplate<P>(name: string, fn: Template<P>): void {
+  templateRegistry.set(name, fn as Template);
+}
+export function hasTemplate(name: string): boolean {
+  return templateRegistry.has(name);
+}
+export function renderTemplate(name: string, params: unknown): UiCardContent {
+  const fn = templateRegistry.get(name);
+  if (!fn) throw new Error(`Unknown template: ${name}`);
+  return fn(params);
+}
+
+// --- 내장 템플릿 ---
+
+export interface ApprovalParams {
+  card_id: string;
+  title?: string;
+  fields: { label: string; value: string; short?: boolean }[];
+  note?: boolean;
+  approveText?: string;
+  rejectText?: string;
+  confirm?: boolean;
+  context?: UiCardContent["context"];
+}
+
+function approval(p: ApprovalParams): UiCardContent {
+  const blocks: Block[] = [{ type: "fields", items: p.fields }];
+  if (p.note) blocks.push({ type: "input", name: "note", label: "Note", placeholder: "Optional" });
+  blocks.push({
+    type: "actions",
+    elements: [
+      {
+        type: "button",
+        action_id: "approve",
+        text: p.approveText ?? "Approve",
+        style: "primary",
+        ...(p.confirm ? { confirm: { title: "Approve", text: "Approve this?" } } : {}),
+      },
+      { type: "button", action_id: "reject", text: p.rejectText ?? "Reject", style: "danger" },
+    ],
+  });
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Approval request",
+    context: p.context,
+    blocks,
+  });
+}
+
+export interface MultiApprovalParams {
+  card_id: string;
+  title?: string;
+  /** 요청 요약 필드(금액·대상 등). */
+  fields?: { label: string; value: string; short?: boolean }[];
+  /** 순차 승인자 목록(순서대로). status 미지정 시 pending(아직 결재 전). */
+  approvers: { name: string; status?: "approved" | "rejected" | "active" | "pending"; note?: string }[];
+  /** 통과에 필요한 최소 승인 수(미지정 시 approvers 전원). */
+  required?: number;
+  /** 진행 안내/메모(markdown). */
+  note?: string;
+  /** 액션(미지정 시 Approve/Reject 기본). 종료 상태면 호출부에서 [] 전달해 숨긴다. */
+  actions?: ActionDef[];
+  state?: UiCardContent["state"];
+  context?: UiCardContent["context"];
+}
+
+/**
+ * 다단계 승인 카드 (HITL) — 0/N 승인 카운터(metric) + 순차 승인자 타임라인(steps) + 액션.
+ * approval.request/.decision 이벤트의 표시면. 승인자 status 가 done/active/error/todo 로 매핑되고
+ * approved/required 카운터가 진행도를 보여준다(색-only 회피: 숫자 병기).
+ */
+function multiApproval(p: MultiApprovalParams): UiCardContent {
+  const required = p.required ?? p.approvers.length;
+  const approved = p.approvers.filter((a) => a.status === "approved").length;
+  const rejected = p.approvers.some((a) => a.status === "rejected");
+  const blocks: Block[] = [];
+  if (p.fields?.length) blocks.push({ type: "fields", items: p.fields });
+  blocks.push({
+    type: "metric",
+    label: "Approvals",
+    value: `${approved}/${required}`,
+    tone: rejected ? "danger" : approved >= required ? "success" : "info",
+  });
+  blocks.push({
+    type: "steps",
+    items: p.approvers.map((a) => ({
+      label: a.name,
+      status:
+        a.status === "approved"
+          ? ("done" as const)
+          : a.status === "rejected"
+            ? ("error" as const)
+            : a.status === "active"
+              ? ("active" as const)
+              : ("todo" as const),
+      note: a.note,
+    })),
+  });
+  if (p.note) blocks.push({ type: "text", text: p.note, markdown: true });
+  const row = actionRow(
+    p.actions ?? [
+      { action_id: "approve", text: "Approve", style: "primary" },
+      { action_id: "reject", text: "Reject", style: "danger" },
+    ],
+  );
+  if (row) blocks.push(row);
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title ?? "Approval workflow",
+    fallback: p.title ?? `Approval ${approved}/${required}`,
+    state: p.state,
+    context: p.context,
+    blocks,
+  });
+}
+
+/** 작업 상태별 텍스트 라벨(색-only 회피 — 단계 note 에 병기). */
+const TASK_STATUS_LABEL: Record<TaskStatus, string> = {
+  todo: "To do",
+  in_progress: "In progress",
+  blocked: "Blocked",
+  done: "Done",
+  cancelled: "Cancelled",
+};
+
+/**
+ * 작업 상태 → steps 블록 상태(done|active|todo|error) 매핑.
+ * blocked→error(빨강·주의 환기)·cancelled→todo(회색·비강조) — 둘은 색이 달라 구분되고, 정확한 상태는
+ * 단계 note 텍스트로 병기한다(steps 블록엔 상태 칩이 없어 색만으로 구분 금지 원칙을 텍스트로 충족).
+ */
+const TASK_STEP_STATUS: Record<TaskStatus, "done" | "active" | "todo" | "error"> = {
+  done: "done",
+  in_progress: "active",
+  blocked: "error",
+  todo: "todo",
+  cancelled: "todo",
+};
+
+export interface TaskListParams {
+  card_id: string;
+  title?: string;
+  /** summarizeTasks(creates, updates) 의 결과 — 카운트/공정률을 손으로 박지 않고 데이터로 받는다. */
+  summary: TaskSummary;
+  actions?: ActionDef[];
+  state?: UiCardContent["state"];
+  context?: UiCardContent["context"];
+}
+
+/**
+ * 작업 진척 카드 (C층 프리미티브) — task.* 이벤트에서 파생한 TaskSummary 를 0/N metric + 전체 progress +
+ * 작업별 steps 로 렌더. 공정률·카운트는 모두 summary(데이터)에서 오고 카드는 손데이터를 만들지 않는다
+ * (done_when "진척도 실데이터"). 상태는 단계 note 에 텍스트로 병기(접근성). multiApproval(0/N)·checklist 와 동형.
+ */
+function taskList(p: TaskListParams): UiCardContent {
+  const s = p.summary;
+  // 완료 카운터의 분모는 공정률과 같은 기준(cancelled 제외) — "1/4"와 25% 가 어긋나지 않게.
+  const countable = s.total - s.cancelled;
+  const blocks: Block[] = [
+    {
+      type: "metric",
+      label: "Done",
+      value: `${s.done}/${countable}`,
+      tone: s.percent === 100 && countable > 0 ? "success" : s.byStatus.blocked > 0 ? "warning" : "info",
+    },
+    { type: "progress", value: s.percent, label: `${s.percent}% complete` },
+    {
+      type: "steps",
+      items: s.tasks.map((t) => {
+        // note = 상태 라벨(색-only 회피) + (진행 중이면 %) + 담당자 + 메모 — 한 줄 맥락.
+        const parts = [TASK_STATUS_LABEL[t.status]];
+        if (t.status === "in_progress" && t.progress != null) parts.push(`${t.progress}%`);
+        if (t.assignees?.length) parts.push(t.assignees.join(", "));
+        if (t.note) parts.push(t.note);
+        return { label: t.title, status: TASK_STEP_STATUS[t.status], note: parts.join(" · ") };
+      }),
+    },
+  ];
+  const row = actionRow(p.actions);
+  if (row) blocks.push(row);
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title ?? "Tasks",
+    // fallback 도 카드 metric 과 같은 분모(cancelled 제외)를 써 미지원 클라에서도 카운트가 일치한다.
+    fallback: p.title ?? `${s.done}/${countable} tasks done`,
+    state: p.state,
+    context: p.context,
+    blocks,
+  });
+}
+
+export interface WizardParams {
+  card_id: string;
+  title?: string;
+  steps: { title?: string; blocks: Block[] }[];
+  submitId?: string;
+  submitText?: string;
+}
+
+function wizard(p: WizardParams): UiCardContent {
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Step-by-step form",
+    steps: p.steps,
+    blocks: [
+      {
+        type: "actions",
+        elements: [
+          { type: "button", action_id: p.submitId ?? "submit", text: p.submitText ?? "Submit", style: "primary" },
+        ],
+      },
+    ],
+  });
+}
+
+export interface ListParams {
+  card_id: string;
+  title?: string;
+  columns: string[];
+  rows: string[][];
+}
+
+function list(p: ListParams): UiCardContent {
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "List",
+    blocks: [{ type: "table", columns: p.columns, rows: p.rows }],
+  });
+}
+
+export interface ProgressParams {
+  card_id: string;
+  title?: string;
+  value?: number;
+  label?: string;
+  steps?: { label: string; status?: "done" | "active" | "todo" | "error"; note?: string }[];
+  state?: UiCardContent["state"];
+}
+
+function progress(p: ProgressParams): UiCardContent {
+  const blocks: Block[] = [{ type: "progress", value: p.value, label: p.label }];
+  if (p.steps) blocks.push({ type: "steps", items: p.steps });
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Progress",
+    state: p.state,
+    blocks,
+  });
+}
+
+export interface InfoParams {
+  card_id: string;
+  title?: string;
+  badge?: { text: string; tone?: "neutral" | "success" | "warning" | "danger" | "info" };
+  fields: { label: string; value: string; short?: boolean }[];
+  note?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 정보/조사 결과 카드 — (선택) badge + 키-값 fields + (선택) 메모 텍스트. */
+function info(p: InfoParams): UiCardContent {
+  const blocks: Block[] = [];
+  if (p.badge) blocks.push({ type: "badge", text: p.badge.text, tone: p.badge.tone });
+  blocks.push({ type: "fields", items: p.fields });
+  if (p.note) blocks.push({ type: "text", text: p.note, markdown: true });
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Info",
+    context: p.context,
+    blocks,
+  });
+}
+
+export interface DocParams {
+  card_id: string;
+  title?: string;
+  fileName: string;
+  fileMeta?: string;
+  summary?: string;
+  previewId?: string;
+  previewText?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 문서/파일 카드 — 파일명·메타 fields + (선택) 요약 + 미리보기 액션. */
+function doc(p: DocParams): UiCardContent {
+  const items = [{ label: "File", value: p.fileName, short: true }];
+  if (p.fileMeta) items.push({ label: "Details", value: p.fileMeta, short: true });
+  const blocks: Block[] = [{ type: "fields", items }];
+  if (p.summary) blocks.push({ type: "text", text: p.summary });
+  blocks.push({
+    type: "actions",
+    elements: [{ type: "button", action_id: p.previewId ?? "preview", text: p.previewText ?? "Preview" }],
+  });
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? p.fileName,
+    context: p.context,
+    blocks,
+  });
+}
+
+export interface PlanParams {
+  card_id: string;
+  title?: string;
+  value?: number;
+  label?: string;
+  steps: { label: string; status?: "done" | "active" | "todo" | "error"; note?: string }[];
+  context?: UiCardContent["context"];
+}
+
+/** 에이전트 실행 계획 카드 — progress + steps 타임라인 (Agent Plan). */
+function plan(p: PlanParams): UiCardContent {
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Execution plan",
+    context: p.context,
+    blocks: [
+      // tone 미지정 → 기본 브랜드(보라) 채움. info 톤이 필요하면 호출부에서 지정. (DESIGN.md §5.5)
+      { type: "progress", value: p.value, label: p.label },
+      { type: "steps", items: p.steps },
+    ],
+  });
+}
+
+export interface FormParams {
+  card_id: string;
+  title?: string;
+  /** input/radio/select/checkbox/text 등 임의 블록 — 마지막에 제출 액션이 붙는다. */
+  blocks: Block[];
+  submitId?: string;
+  submitText?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 단일 단계 입력 폼 카드 — 임의 입력 블록 + 제출 액션(마법사 wizard 와 달리 단일 화면). */
+function form(p: FormParams): UiCardContent {
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title,
+    fallback: p.title ?? "Form",
+    context: p.context,
+    blocks: [
+      ...p.blocks,
+      {
+        type: "actions",
+        elements: [
+          { type: "button", action_id: p.submitId ?? "submit", text: p.submitText ?? "Submit", style: "primary" },
+        ],
+      },
+    ],
+  });
+}
+
+// 도메인색이 강한 SCM(Forgejo) 템플릿(scmRef/prReview/ciRun)은 코어가 아니라 plugin-forgejo 가
+// 소유한다 — register() 에서 registerTemplate 로 등록(packages/plugin-forgejo/src/templates.ts).
+// 코어 templates.* 는 도메인 무관 프리미티브만 유지한다("도메인=플러그인" 가드레일).
+
+export interface ScorecardParams {
+  card_id: string;
+  title?: string;
+  progress?: number;
+  progressLabel?: string;
+  /** 기준(DoD) 체크리스트 */
+  criteria?: { label: string; done: boolean }[];
+  /** 임팩트 지표 */
+  metrics?: { label: string; value: string; target?: string; delta?: string; tone?: Tone }[];
+  context?: UiCardContent["context"];
+}
+
+/** 진척도·임팩트 스코어카드 — 공정률(progress) + 기준 체크리스트 + 임팩트 KPI(metric). */
+function scorecard(p: ScorecardParams): UiCardContent {
+  const blocks: Block[] = [];
+  if (p.progress != null || p.progressLabel) {
+    blocks.push({ type: "progress", value: p.progress, label: p.progressLabel });
+  }
+  for (const m of p.metrics ?? []) {
+    blocks.push({ type: "metric", label: m.label, value: m.value, target: m.target, delta: m.delta, tone: m.tone });
+  }
+  if (p.criteria?.length) {
+    blocks.push({
+      type: "steps",
+      items: p.criteria.map((c) => ({ label: c.label, status: c.done ? ("done" as const) : ("todo" as const) })),
+    });
+  }
+  return buildUiCardContent({
+    card_id: p.card_id,
+    title: p.title ?? "Progress · Impact",
+    fallback: p.title ?? "Progress/Impact",
+    context: p.context,
+    blocks,
+  });
+}
+
+// --- 도메인 템플릿 1차 (Phase 1 신규 블록 활용) ---
+
+/** 액션 버튼 정의(템플릿 공용). */
+export type ActionDef = { action_id: string; text: string; style?: ButtonStyle; value?: string };
+
+/** ActionDef[] → actions 블록(없으면 null). */
+function actionRow(actions?: ActionDef[]): Block | null {
+  if (!actions?.length) return null;
+  return {
+    type: "actions",
+    elements: actions.map((a) => ({ type: "button", action_id: a.action_id, text: a.text, style: a.style, value: a.value })),
+  };
+}
+
+export interface ContactCardParams {
+  card_id: string;
+  title?: string;
+  name: string;
+  /** 직함/역할(아바타 보조텍스트). */
+  role?: string;
+  status?: "online" | "away" | "busy" | "offline";
+  fields?: { label: string; value: string; short?: boolean }[];
+  /** 연결된 엔티티(예: CRM 리드) 칩. */
+  ref?: { entity?: string; label: string; url?: string };
+  actions?: ActionDef[];
+  context?: UiCardContent["context"];
+}
+
+/** 인물 카드 — 아바타 + 연락 fields + (선택) 엔티티 칩 + 액션. */
+function contactCard(p: ContactCardParams): UiCardContent {
+  const blocks: Block[] = [{ type: "avatar", name: p.name, subtitle: p.role, status: p.status }];
+  if (p.fields?.length) blocks.push({ type: "fields", items: p.fields });
+  if (p.ref) blocks.push({ type: "entityRef", entity: p.ref.entity, label: p.ref.label, url: p.ref.url, tone: "info" });
+  const row = actionRow(p.actions);
+  if (row) blocks.push(row);
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? p.name, context: p.context, blocks });
+}
+
+export interface DigestParams {
+  card_id: string;
+  title?: string;
+  summary: string;
+  /** 핵심 포인트(불릿). */
+  points?: string[];
+  /** 출처 — 칩/링크. */
+  sources?: { label: string; url?: string }[];
+  actions?: ActionDef[];
+  context?: UiCardContent["context"];
+}
+
+/** AI 브리핑 카드 — 요약 + 포인트 + 출처 칩 + 액션. */
+function digest(p: DigestParams): UiCardContent {
+  const blocks: Block[] = [{ type: "text", text: p.summary, markdown: true }];
+  if (p.points?.length) blocks.push({ type: "text", text: p.points.map((pt) => `- ${pt}`).join("\n"), markdown: true });
+  if (p.sources?.length) {
+    blocks.push({ type: "context", elements: ["Sources"] });
+    for (const s of p.sources) blocks.push({ type: "entityRef", entity: "source", label: s.label, url: s.url });
+  }
+  const row = actionRow(p.actions);
+  if (row) blocks.push(row);
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Digest", context: p.context, blocks });
+}
+
+export interface IncidentParams {
+  card_id: string;
+  title?: string;
+  /** 심각도 라벨(예: "SEV1"). */
+  severity?: string;
+  /** 심각도 톤(기본 warning). */
+  tone?: Tone;
+  summary?: string;
+  fields?: { label: string; value: string; short?: boolean }[];
+  steps?: { label: string; status?: "done" | "active" | "todo" | "error"; note?: string }[];
+  actions?: ActionDef[];
+  context?: UiCardContent["context"];
+}
+
+/** 인시던트 카드 — 심각도 콜아웃 + 메타 fields + 대응 steps + 액션. */
+function incident(p: IncidentParams): UiCardContent {
+  const blocks: Block[] = [
+    { type: "callout", tone: p.tone ?? "warning", title: p.severity ?? "Incident", text: p.summary ?? p.title ?? "Incident reported" },
+  ];
+  if (p.fields?.length) blocks.push({ type: "fields", items: p.fields });
+  if (p.steps?.length) blocks.push({ type: "steps", items: p.steps });
+  const row = actionRow(p.actions);
+  if (row) blocks.push(row);
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? p.severity ?? "Incident", context: p.context, blocks });
+}
+
+export interface KpiGridParams {
+  card_id: string;
+  title?: string;
+  metrics: { label: string; value: string; target?: string; delta?: string; tone?: Tone }[];
+  /** 선택 차트(추세). */
+  chart?: {
+    variant: "sparkline" | "bar" | "line" | "donut";
+    data: { label?: string; value: number; tone?: Tone }[];
+    caption?: string;
+    unit?: string;
+  };
+  context?: UiCardContent["context"];
+}
+
+/** KPI 그리드 카드 — metric 묶음 + (선택) 추세 차트. */
+function kpiGrid(p: KpiGridParams): UiCardContent {
+  const blocks: Block[] = p.metrics.map((m) => ({
+    type: "metric",
+    label: m.label,
+    value: m.value,
+    target: m.target,
+    delta: m.delta,
+    tone: m.tone,
+  }));
+  if (p.chart) {
+    blocks.push({ type: "chart", variant: p.chart.variant, data: p.chart.data, caption: p.chart.caption, unit: p.chart.unit });
+  }
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "KPIs", context: p.context, blocks });
+}
+
+// --- 도메인 템플릿 2차 ---
+
+export interface InvoiceParams {
+  card_id: string;
+  title?: string;
+  number?: string;
+  vendor?: string;
+  amount: string;
+  due?: string;
+  /** 상태 배지(예: {label:"Pending", tone:"warning"}). */
+  status?: { label: string; tone?: Tone };
+  /** 액션(미지정 시 Approve/Reject 기본). */
+  actions?: ActionDef[];
+  context?: UiCardContent["context"];
+}
+
+/** 송장 카드 — 금액·기한 등 fields + (선택) 상태 배지 + 승인/반려 액션. */
+function invoice(p: InvoiceParams): UiCardContent {
+  const blocks: Block[] = [];
+  if (p.status) blocks.push({ type: "badge", text: p.status.label, tone: p.status.tone });
+  const items: { label: string; value: string; short?: boolean }[] = [];
+  if (p.number) items.push({ label: "Invoice", value: p.number, short: true });
+  if (p.vendor) items.push({ label: "Vendor", value: p.vendor, short: true });
+  items.push({ label: "Amount", value: p.amount, short: true });
+  if (p.due) items.push({ label: "Due", value: p.due, short: true });
+  blocks.push({ type: "fields", items });
+  const row = actionRow(
+    p.actions ?? [
+      { action_id: "approve", text: "Approve", style: "primary" },
+      { action_id: "reject", text: "Reject", style: "danger" },
+    ],
+  );
+  if (row) blocks.push(row);
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? `Invoice ${p.number ?? ""}`.trim(), context: p.context, blocks });
+}
+
+export interface EstimateParams {
+  card_id: string;
+  title?: string;
+  lines: { label: string; qty?: string; amount: string }[];
+  total?: string;
+  note?: string;
+  actions?: ActionDef[];
+  context?: UiCardContent["context"];
+}
+
+/** 견적 카드 — 라인아이템 table + (선택) 합계 metric + 액션. */
+function estimate(p: EstimateParams): UiCardContent {
+  const blocks: Block[] = [
+    { type: "table", columns: ["Item", "Qty", "Amount"], rows: p.lines.map((l) => [l.label, l.qty ?? "", l.amount]) },
+  ];
+  if (p.total) blocks.push({ type: "metric", label: "Total", value: p.total, tone: "info" });
+  if (p.note) blocks.push({ type: "text", text: p.note });
+  const row = actionRow(p.actions);
+  if (row) blocks.push(row);
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Estimate", context: p.context, blocks });
+}
+
+export interface ComparisonParams {
+  card_id: string;
+  title?: string;
+  /** 비교 대상 열 제목(예: ["Plan A","Plan B"]). */
+  options: string[];
+  /** 각 기준 행: label + 옵션 수만큼의 값. */
+  rows: { label: string; values: string[] }[];
+  context?: UiCardContent["context"];
+}
+
+/** 비교 카드 — A vs B 표(첫 열=기준, 나머지=옵션 값). */
+function comparison(p: ComparisonParams): UiCardContent {
+  const blocks: Block[] = [
+    { type: "table", columns: ["", ...p.options], rows: p.rows.map((r) => [r.label, ...r.values]) },
+  ];
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Comparison", context: p.context, blocks });
+}
+
+export interface ChecklistParams {
+  card_id: string;
+  title?: string;
+  items: { label: string; done?: boolean; note?: string }[];
+  /** 담당자(아바타로 표시). */
+  owner?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 체크리스트 카드 — (선택) 담당 아바타 + 진행률 progress + 항목 steps(done/todo). */
+function checklist(p: ChecklistParams): UiCardContent {
+  const total = p.items.length;
+  const done = p.items.filter((i) => i.done).length;
+  const pct = total ? Math.round((done / total) * 100) : 0;
+  const blocks: Block[] = [];
+  if (p.owner) blocks.push({ type: "avatar", name: p.owner, subtitle: `Owner · ${done}/${total} done` });
+  blocks.push({ type: "progress", value: pct, label: `${done}/${total} complete` });
+  blocks.push({
+    type: "steps",
+    items: p.items.map((i) => ({ label: i.label, status: i.done ? ("done" as const) : ("todo" as const), note: i.note })),
+  });
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Checklist", context: p.context, blocks });
+}
+
+export interface MeetingParams {
+  card_id: string;
+  title?: string;
+  agenda?: string;
+  when?: string;
+  duration?: string;
+  attendees?: string[];
+  /** 시간 후보(라디오). 미지정 시 즉시 확정 버튼만. */
+  options?: { label: string; value: string }[];
+  confirmText?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 회의 카드 — 안건/일시 fields + 참석자 avatarGroup + (선택) 시간 후보 radio + 확정 액션. */
+function meeting(p: MeetingParams): UiCardContent {
+  const blocks: Block[] = [];
+  const items: { label: string; value: string; short?: boolean }[] = [];
+  if (p.agenda) items.push({ label: "Agenda", value: p.agenda });
+  if (p.when) items.push({ label: "When", value: p.when, short: true });
+  if (p.duration) items.push({ label: "Duration", value: p.duration, short: true });
+  if (items.length) blocks.push({ type: "fields", items });
+  if (p.attendees?.length) blocks.push({ type: "avatarGroup", label: "Attendees", people: p.attendees.map((a) => ({ name: a })) });
+  if (p.options?.length) {
+    blocks.push({ type: "radio", name: "slot", label: "Pick a slot", options: p.options, value: p.options[0]?.value });
+  }
+  blocks.push({
+    type: "actions",
+    elements: [{ type: "button", action_id: "confirm_schedule", text: p.confirmText ?? "Confirm time", style: "primary" }],
+  });
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Meeting", context: p.context, blocks });
+}
+
+export interface ErrorRecoveryParams {
+  card_id: string;
+  title?: string;
+  message: string;
+  /** 기술 상세(코드/로그). */
+  detail?: string;
+  retryText?: string;
+  escalateText?: string;
+  context?: UiCardContent["context"];
+}
+
+/** 오류 복구 카드 — danger 콜아웃 + (선택) 상세 code + Retry/Escalate 액션. */
+function errorRecovery(p: ErrorRecoveryParams): UiCardContent {
+  const blocks: Block[] = [{ type: "callout", tone: "danger", title: p.title ?? "Something went wrong", text: p.message }];
+  if (p.detail) blocks.push({ type: "code", code: p.detail });
+  blocks.push({
+    type: "actions",
+    elements: [
+      { type: "button", action_id: "retry", text: p.retryText ?? "Retry", style: "primary" },
+      { type: "button", action_id: "escalate", text: p.escalateText ?? "Escalate" },
+    ],
+  });
+  return buildUiCardContent({ card_id: p.card_id, title: p.title, fallback: p.title ?? "Error", context: p.context, blocks });
+}
+
+/** 내장 템플릿 모음 (타입드 SDK 진입점). */
+export const templates = {
+  approval,
+  multiApproval,
+  taskList,
+  wizard,
+  list,
+  progress,
+  info,
+  doc,
+  plan,
+  form,
+  scorecard,
+  contactCard,
+  digest,
+  incident,
+  kpiGrid,
+  invoice,
+  estimate,
+  comparison,
+  checklist,
+  meeting,
+  errorRecovery,
+};
+
+registerTemplate<ApprovalParams>("approval", approval);
+registerTemplate<MultiApprovalParams>("multiApproval", multiApproval);
+registerTemplate<TaskListParams>("taskList", taskList);
+registerTemplate<WizardParams>("wizard", wizard);
+registerTemplate<ListParams>("list", list);
+registerTemplate<ProgressParams>("progress", progress);
+registerTemplate<InfoParams>("info", info);
+registerTemplate<DocParams>("doc", doc);
+registerTemplate<PlanParams>("plan", plan);
+registerTemplate<FormParams>("form", form);
+registerTemplate<ScorecardParams>("scorecard", scorecard);
+registerTemplate<ContactCardParams>("contactCard", contactCard);
+registerTemplate<DigestParams>("digest", digest);
+registerTemplate<IncidentParams>("incident", incident);
+registerTemplate<KpiGridParams>("kpiGrid", kpiGrid);
+registerTemplate<InvoiceParams>("invoice", invoice);
+registerTemplate<EstimateParams>("estimate", estimate);
+registerTemplate<ComparisonParams>("comparison", comparison);
+registerTemplate<ChecklistParams>("checklist", checklist);
+registerTemplate<MeetingParams>("meeting", meeting);
+registerTemplate<ErrorRecoveryParams>("errorRecovery", errorRecovery);