From aa5dbc8088f9f5399e5728346ce6ceb4abafa2ca Mon Sep 17 00:00:00 2001
From: Cyber-preacher <davidkavazi@gmail.com>
Date: Wed, 15 Apr 2026 17:22:34 +0400
Subject: [PATCH 1/3] Add proposal deliberation UI

---
 src/app/App.tsx                               |   4 +-
 .../discussions/ThreadPrimitives.tsx          | 398 ++++++++++++++++++
 src/lib/apiClient.ts                          | 164 +++++---
 src/pages/proposals/ProposalChamber.tsx       |   3 +
 src/pages/proposals/ProposalChamberVeto.tsx   |   3 +
 src/pages/proposals/ProposalCitizenVeto.tsx   |   3 +
 src/pages/proposals/ProposalDeliberation.tsx  | 395 +++++++++++++++++
 src/pages/proposals/ProposalFinished.tsx      |   3 +
 src/pages/proposals/ProposalFormation.tsx     |   3 +
 src/pages/proposals/ProposalPP.tsx            |   3 +
 src/pages/proposals/ProposalReferendum.tsx    |   3 +
 src/pages/proposals/Proposals.tsx             |  18 +-
 src/types/api.ts                              |  52 +++
 13 files changed, 992 insertions(+), 60 deletions(-)
 create mode 100644 src/components/discussions/ThreadPrimitives.tsx
 create mode 100644 src/pages/proposals/ProposalDeliberation.tsx

diff --git a/src/app/App.tsx b/src/app/App.tsx
index 00b5f74..4dacfef 100644
--- a/src/app/App.tsx
+++ b/src/app/App.tsx
@@ -4,12 +4,12 @@ import { AuthProvider } from "@/app/auth/AuthContext";
 import AppRoutes from "./AppRoutes";
 
 const ScrollToTopOnRouteChange: React.FC = () => {
-  const { pathname, search } = useLocation();
+  const { pathname } = useLocation();
 
   useEffect(() => {
     document.title = "Vortex Sim";
     window.scrollTo({ top: 0, left: 0, behavior: "auto" });
-  }, [pathname, search]);
+  }, [pathname]);
 
   return null;
 };
diff --git a/src/components/discussions/ThreadPrimitives.tsx b/src/components/discussions/ThreadPrimitives.tsx
new file mode 100644
index 0000000..ab87dd7
--- /dev/null
+++ b/src/components/discussions/ThreadPrimitives.tsx
@@ -0,0 +1,398 @@
+import type { FormEventHandler, ReactNode } from "react";
+
+import { AddressInline } from "@/components/AddressInline";
+import { Surface } from "@/components/Surface";
+import { Button } from "@/components/primitives/button";
+import { Input } from "@/components/primitives/input";
+import { Select } from "@/components/primitives/select";
+import { formatDateTime } from "@/lib/dateTime";
+
+type DiscussionOption<TValue extends string = string> = {
+  value: TValue;
+  label: string;
+};
+
+export type DiscussionStatusOption<TValue extends string = string> =
+  DiscussionOption<TValue>;
+
+type DiscussionThreadPermissions = {
+  canReply?: boolean;
+  canTransition?: boolean;
+};
+
+type DiscussionThreadListItem<
+  TCategory extends string = string,
+  TStatus extends string = string,
+> = {
+  id: string;
+  category: TCategory;
+  status: TStatus;
+  title: string;
+  body: string;
+  replies: number;
+  updatedAt: string;
+  permissions: DiscussionThreadPermissions;
+};
+
+type DiscussionThreadDetailItem<
+  TCategory extends string = string,
+  TStatus extends string = string,
+> = DiscussionThreadListItem<TCategory, TStatus> & {
+  authorAddress: string;
+  createdAt: string;
+};
+
+type DiscussionThreadMessage = {
+  id: string;
+  authorAddress: string;
+  body: string;
+  createdAt: string;
+};
+
+const textareaClassName =
+  "min-h-[96px] w-full resize-y rounded-xl border border-border bg-panel-alt px-3 py-2 text-sm text-text shadow-[var(--shadow-control)] focus-visible:ring-2 focus-visible:ring-[color:var(--primary-dim)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-60";
+
+type ThreadCategoryFilterProps<TValue extends string> = {
+  options: Array<DiscussionOption<TValue>>;
+  value: TValue;
+  onChange: (value: TValue) => void;
+};
+
+export function ThreadCategoryFilter<TValue extends string>({
+  options,
+  value,
+  onChange,
+}: ThreadCategoryFilterProps<TValue>) {
+  return (
+    <div className="mt-4 flex flex-wrap gap-2">
+      {options.map((option) => (
+        <Button
+          key={option.value}
+          type="button"
+          size="sm"
+          variant={value === option.value ? "primary" : "ghost"}
+          onClick={() => onChange(option.value)}
+        >
+          {option.label}
+        </Button>
+      ))}
+    </div>
+  );
+}
+
+type ThreadComposerProps<TCategory extends string> = {
+  categoryOptions: Array<DiscussionOption<TCategory>>;
+  categoryValue: TCategory;
+  onCategoryChange: (value: TCategory) => void;
+  title: string;
+  onTitleChange: (value: string) => void;
+  body: string;
+  onBodyChange: (value: string) => void;
+  onSubmit: FormEventHandler<HTMLFormElement>;
+  canCreate: boolean;
+  busy: boolean;
+  disabledMessage?: string | null;
+  titlePlaceholder?: string;
+  bodyPlaceholder?: string;
+  submitLabel?: string;
+  busyLabel?: string;
+};
+
+export function ThreadComposer<TCategory extends string>({
+  categoryOptions,
+  categoryValue,
+  onCategoryChange,
+  title,
+  onTitleChange,
+  body,
+  onBodyChange,
+  onSubmit,
+  canCreate,
+  busy,
+  disabledMessage,
+  titlePlaceholder = "Thread title",
+  bodyPlaceholder = "Write the opening post",
+  submitLabel = "Start thread",
+  busyLabel = "Posting...",
+}: ThreadComposerProps<TCategory>) {
+  return (
+    <form onSubmit={onSubmit} className="mt-4 space-y-3">
+      <div className="grid gap-3 md:grid-cols-[180px_minmax(0,1fr)]">
+        <Select
+          value={categoryValue}
+          onChange={(event) =>
+            onCategoryChange(event.target.value as TCategory)
+          }
+          disabled={!canCreate || busy}
+          aria-label="Thread category"
+        >
+          {categoryOptions.map((option) => (
+            <option key={option.value} value={option.value}>
+              {option.label}
+            </option>
+          ))}
+        </Select>
+        <Input
+          value={title}
+          onChange={(event) => onTitleChange(event.target.value)}
+          placeholder={titlePlaceholder}
+          disabled={!canCreate || busy}
+        />
+      </div>
+      <textarea
+        value={body}
+        onChange={(event) => onBodyChange(event.target.value)}
+        placeholder={bodyPlaceholder}
+        disabled={!canCreate || busy}
+        className={textareaClassName}
+      />
+      <div className="flex flex-wrap items-center gap-2">
+        <Button
+          type="submit"
+          size="sm"
+          disabled={!canCreate || busy || !title.trim() || !body.trim()}
+        >
+          {busy ? busyLabel : submitLabel}
+        </Button>
+        {disabledMessage ? (
+          <span className="text-xs text-muted">{disabledMessage}</span>
+        ) : null}
+      </div>
+    </form>
+  );
+}
+
+type ThreadListProps<
+  TCategory extends string,
+  TStatus extends string,
+  TThread extends DiscussionThreadListItem<TCategory, TStatus>,
+> = {
+  threads: TThread[];
+  selectedThreadId: string | null;
+  emptyMessage: string;
+  categoryLabel: (value: TCategory) => string;
+  statusLabel: (value: TStatus) => string;
+  onSelect: (threadId: string) => void;
+};
+
+export function ThreadList<
+  TCategory extends string,
+  TStatus extends string,
+  TThread extends DiscussionThreadListItem<TCategory, TStatus>,
+>({
+  threads,
+  selectedThreadId,
+  emptyMessage,
+  categoryLabel,
+  statusLabel,
+  onSelect,
+}: ThreadListProps<TCategory, TStatus, TThread>) {
+  if (threads.length === 0) {
+    return (
+      <Surface
+        variant="panelAlt"
+        radius="xl"
+        shadow="none"
+        className="px-4 py-4 text-sm text-muted"
+      >
+        {emptyMessage}
+      </Surface>
+    );
+  }
+
+  return (
+    <>
+      {threads.map((thread) => (
+        <Surface
+          key={thread.id}
+          as="article"
+          variant={selectedThreadId === thread.id ? "panel" : "panelAlt"}
+          radius="xl"
+          shadow="none"
+          role="button"
+          tabIndex={0}
+          className="cursor-pointer px-4 py-3 transition hover:border-primary/60 focus-visible:ring-2 focus-visible:ring-[color:var(--primary-dim)] focus-visible:outline-none"
+          onClick={() => onSelect(thread.id)}
+          onKeyDown={(event) => {
+            if (event.key !== "Enter" && event.key !== " ") return;
+            event.preventDefault();
+            onSelect(thread.id);
+          }}
+        >
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+            <div className="min-w-0 flex-1 text-left">
+              <span className="text-xs font-semibold text-muted">
+                {categoryLabel(thread.category)} · {statusLabel(thread.status)}
+              </span>
+              <h3 className="mt-1 text-base font-semibold text-text">
+                {thread.title}
+              </h3>
+              <p className="mt-1 line-clamp-2 text-sm text-muted">
+                {thread.body}
+              </p>
+              <p className="mt-2 text-xs text-muted">
+                {thread.replies} replies · Updated{" "}
+                {formatDateTime(thread.updatedAt)}
+              </p>
+            </div>
+          </div>
+        </Surface>
+      ))}
+    </>
+  );
+}
+
+type ThreadDetailProps<
+  TCategory extends string,
+  TStatus extends string,
+  TThread extends DiscussionThreadDetailItem<TCategory, TStatus>,
+  TMessage extends DiscussionThreadMessage,
+> = {
+  detail: {
+    thread: TThread;
+    messages: TMessage[];
+  } | null;
+  errorText: string | null;
+  busy: boolean;
+  emptyMessage: string;
+  categoryLabel: (value: TCategory) => string;
+  statusLabel: (value: TStatus) => string;
+  statusOptions: Array<DiscussionStatusOption<TStatus>>;
+  replyBody: string;
+  onReplyBodyChange: (value: string) => void;
+  onReply: FormEventHandler<HTMLFormElement>;
+  onTransition: (status: TStatus) => void | Promise<void>;
+  replyPlaceholder?: (thread: TThread) => string;
+  renderAuthor?: (address: string) => ReactNode;
+};
+
+export function ThreadDetail<
+  TCategory extends string,
+  TStatus extends string,
+  TThread extends DiscussionThreadDetailItem<TCategory, TStatus>,
+  TMessage extends DiscussionThreadMessage,
+>({
+  detail,
+  errorText,
+  busy,
+  emptyMessage,
+  categoryLabel,
+  statusLabel,
+  statusOptions,
+  replyBody,
+  onReplyBodyChange,
+  onReply,
+  onTransition,
+  replyPlaceholder = () => "Write a reply",
+  renderAuthor = (address) => (
+    <AddressInline
+      address={address}
+      className="text-text"
+      textClassName="text-xs [overflow-wrap:anywhere] break-words"
+    />
+  ),
+}: ThreadDetailProps<TCategory, TStatus, TThread, TMessage>) {
+  return (
+    <Surface variant="panelAlt" radius="xl" shadow="none" className="p-4">
+      {errorText ? (
+        <p className="text-sm text-destructive">{errorText}</p>
+      ) : !detail ? (
+        <p className="text-sm text-muted">{emptyMessage}</p>
+      ) : (
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <div className="flex flex-wrap items-center gap-2 text-xs font-semibold text-muted">
+              <span>{categoryLabel(detail.thread.category)}</span>
+              <span>{statusLabel(detail.thread.status)}</span>
+              <span>{formatDateTime(detail.thread.createdAt)}</span>
+            </div>
+            <h3 className="text-lg font-semibold text-text">
+              {detail.thread.title}
+            </h3>
+            {renderAuthor(detail.thread.authorAddress)}
+            <p className="text-sm whitespace-pre-wrap text-text">
+              {detail.thread.body}
+            </p>
+          </div>
+
+          {detail.thread.permissions.canTransition ? (
+            <div className="flex flex-wrap items-center gap-2">
+              <Select
+                value={detail.thread.status}
+                onChange={(event) =>
+                  void onTransition(event.target.value as TStatus)
+                }
+                disabled={busy}
+                className="max-w-[180px]"
+                aria-label="Thread status"
+              >
+                {statusOptions.map((option) => (
+                  <option key={option.value} value={option.value}>
+                    {option.label}
+                  </option>
+                ))}
+              </Select>
+            </div>
+          ) : null}
+
+          <div className="space-y-2">
+            <p className="text-xs font-semibold text-muted">Replies</p>
+            {detail.messages.length === 0 ? (
+              <p className="text-sm text-muted">No replies yet.</p>
+            ) : (
+              detail.messages.map((message) => (
+                <Surface
+                  key={message.id}
+                  variant="panel"
+                  radius="xl"
+                  shadow="none"
+                  className="px-3 py-2"
+                >
+                  <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+                    <div className="min-w-0 space-y-1">
+                      {renderAuthor(message.authorAddress)}
+                      <p className="text-xs text-muted">
+                        {formatDateTime(message.createdAt)}
+                      </p>
+                      <p className="text-sm whitespace-pre-wrap text-text">
+                        {message.body}
+                      </p>
+                    </div>
+                  </div>
+                </Surface>
+              ))
+            )}
+          </div>
+
+          <form onSubmit={onReply} className="space-y-3">
+            <textarea
+              value={replyBody}
+              onChange={(event) => onReplyBodyChange(event.target.value)}
+              placeholder={replyPlaceholder(detail.thread)}
+              disabled={!detail.thread.permissions.canReply || busy}
+              className={textareaClassName}
+            />
+            <div className="flex flex-wrap items-center gap-2">
+              <Button
+                type="submit"
+                size="sm"
+                disabled={
+                  busy ||
+                  !detail.thread.permissions.canReply ||
+                  !replyBody.trim()
+                }
+              >
+                {busy ? "Posting..." : "Reply"}
+              </Button>
+              {!detail.thread.permissions.canReply ? (
+                <span className="text-xs text-muted">
+                  This thread is read-only for you.
+                </span>
+              ) : null}
+            </div>
+          </form>
+        </div>
+      )}
+    </Surface>
+  );
+}
diff --git a/src/lib/apiClient.ts b/src/lib/apiClient.ts
index 84a6433..b8e4f3d 100644
--- a/src/lib/apiClient.ts
+++ b/src/lib/apiClient.ts
@@ -29,6 +29,10 @@ import type {
   GetProposalTimelineResponse,
   HumanNodeProfileDto,
   ProposalDraftDetailDto,
+  ProposalThreadDetailDto,
+  ProposalThreadDto,
+  ProposalThreadListDto,
+  ProposalThreadMessageDto,
   ProposalStatusDto,
   PoolProposalPageDto,
 } from "@/types/api";
@@ -283,6 +287,21 @@ export async function apiProposalTimeline(
   );
 }
 
+export async function apiProposalThreads(
+  id: string,
+): Promise<ProposalThreadListDto> {
+  return await apiGet<ProposalThreadListDto>(`/api/proposals/${id}/threads`);
+}
+
+export async function apiProposalThreadDetail(
+  proposalId: string,
+  threadId: string,
+): Promise<ProposalThreadDetailDto> {
+  return await apiGet<ProposalThreadDetailDto>(
+    `/api/proposals/${proposalId}/threads/${threadId}`,
+  );
+}
+
 export async function apiProposalStatus(
   id: string,
 ): Promise<ProposalStatusDto> {
@@ -467,6 +486,94 @@ export async function apiChamberThreadReply(input: {
   );
 }
 
+export async function apiProposalThreadCreate(input: {
+  proposalId: string;
+  category?: ProposalThreadDto["category"];
+  title: string;
+  body: string;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "proposal.thread.create";
+  proposalId: string;
+  thread: ProposalThreadDto;
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "proposal.thread.create",
+      payload: {
+        proposalId: input.proposalId,
+        category: input.category ?? "general",
+        title: input.title,
+        body: input.body,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
+export async function apiProposalThreadReply(input: {
+  proposalId: string;
+  threadId: string;
+  body: string;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "proposal.thread.reply";
+  proposalId: string;
+  threadId: string;
+  message: ProposalThreadMessageDto;
+  replies: number;
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "proposal.thread.reply",
+      payload: {
+        proposalId: input.proposalId,
+        threadId: input.threadId,
+        body: input.body,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
+export async function apiProposalThreadTransition(input: {
+  proposalId: string;
+  threadId: string;
+  status: ProposalThreadDto["status"];
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "proposal.thread.transition";
+  proposalId: string;
+  thread: { id: string; status: ProposalThreadDto["status"] };
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "proposal.thread.transition",
+      payload: {
+        proposalId: input.proposalId,
+        threadId: input.threadId,
+        status: input.status,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
 export async function apiChamberChatPost(input: {
   chamberId: string;
   message: string;
@@ -1248,63 +1355,6 @@ export async function apiFactionThreadTransition(input: {
   );
 }
 
-export async function apiFactionThreadDelete(input: {
-  factionId: string;
-  threadId: string;
-  idempotencyKey?: string;
-}): Promise<{
-  ok: true;
-  type: "faction.thread.delete";
-  factionId: string;
-  threadId: string;
-  deleted: true;
-}> {
-  return await apiPost(
-    "/api/command",
-    {
-      type: "faction.thread.delete",
-      payload: {
-        factionId: input.factionId,
-        threadId: input.threadId,
-      },
-      idempotencyKey: input.idempotencyKey,
-    },
-    input.idempotencyKey
-      ? { headers: { "idempotency-key": input.idempotencyKey } }
-      : undefined,
-  );
-}
-
-export async function apiFactionThreadReplyDelete(input: {
-  factionId: string;
-  threadId: string;
-  messageId: string;
-  idempotencyKey?: string;
-}): Promise<{
-  ok: true;
-  type: "faction.thread.reply.delete";
-  factionId: string;
-  threadId: string;
-  messageId: string;
-  deleted: true;
-}> {
-  return await apiPost(
-    "/api/command",
-    {
-      type: "faction.thread.reply.delete",
-      payload: {
-        factionId: input.factionId,
-        threadId: input.threadId,
-        messageId: input.messageId,
-      },
-      idempotencyKey: input.idempotencyKey,
-    },
-    input.idempotencyKey
-      ? { headers: { "idempotency-key": input.idempotencyKey } }
-      : undefined,
-  );
-}
-
 export async function apiFactionInitiativeCreate(input: {
   factionId: string;
   title: string;
diff --git a/src/pages/proposals/ProposalChamber.tsx b/src/pages/proposals/ProposalChamber.tsx
index e4684c9..bd4d303 100644
--- a/src/pages/proposals/ProposalChamber.tsx
+++ b/src/pages/proposals/ProposalChamber.tsx
@@ -32,6 +32,7 @@ import {
 } from "./useProposalStageSync";
 import { useAuth } from "@/app/auth/AuthContext";
 import { CitizenVetoActions } from "./CitizenVetoActions";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalChamber: React.FC = () => {
   const { id } = useParams();
@@ -622,6 +623,8 @@ const ProposalChamber: React.FC = () => {
         />
       ) : null}
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/ProposalChamberVeto.tsx b/src/pages/proposals/ProposalChamberVeto.tsx
index c596c27..7a2ad41 100644
--- a/src/pages/proposals/ProposalChamberVeto.tsx
+++ b/src/pages/proposals/ProposalChamberVeto.tsx
@@ -26,6 +26,7 @@ import {
   useProposalTransitionNotice,
 } from "./useProposalStageSync";
 import { useAuth } from "@/app/auth/AuthContext";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalChamberVeto: React.FC = () => {
   const { id } = useParams();
@@ -455,6 +456,8 @@ const ProposalChamberVeto: React.FC = () => {
         showBudgetScope={proposal.formationEligible}
       />
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/ProposalCitizenVeto.tsx b/src/pages/proposals/ProposalCitizenVeto.tsx
index 122c800..0433e32 100644
--- a/src/pages/proposals/ProposalCitizenVeto.tsx
+++ b/src/pages/proposals/ProposalCitizenVeto.tsx
@@ -25,6 +25,7 @@ import {
   useProposalTransitionNotice,
 } from "./useProposalStageSync";
 import { useAuth } from "@/app/auth/AuthContext";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalCitizenVeto: React.FC = () => {
   const { id } = useParams();
@@ -369,6 +370,8 @@ const ProposalCitizenVeto: React.FC = () => {
         showBudgetScope={proposal.formationEligible}
       />
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/ProposalDeliberation.tsx b/src/pages/proposals/ProposalDeliberation.tsx
new file mode 100644
index 0000000..af3cf93
--- /dev/null
+++ b/src/pages/proposals/ProposalDeliberation.tsx
@@ -0,0 +1,395 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type FormEvent,
+} from "react";
+import { useSearchParams } from "react-router";
+
+import { useAuth } from "@/app/auth/AuthContext";
+import { Surface } from "@/components/Surface";
+import {
+  ThreadCategoryFilter,
+  ThreadComposer,
+  ThreadDetail,
+  ThreadList,
+  type DiscussionStatusOption,
+} from "@/components/discussions/ThreadPrimitives";
+import {
+  apiProposalThreadCreate,
+  apiProposalThreadDetail,
+  apiProposalThreadReply,
+  apiProposalThreads,
+  apiProposalThreadTransition,
+} from "@/lib/apiClient";
+import { formatLoadError } from "@/lib/errorFormatting";
+import type {
+  ProposalThreadCategoryDto,
+  ProposalThreadDetailDto,
+  ProposalThreadDto,
+  ProposalThreadListDto,
+} from "@/types/api";
+
+const CATEGORY_OPTIONS: Array<{
+  value: ProposalThreadCategoryDto | "all";
+  label: string;
+}> = [
+  { value: "all", label: "All" },
+  { value: "question", label: "Questions" },
+  { value: "concern", label: "Concerns" },
+  { value: "amendment", label: "Amendments" },
+  { value: "support", label: "Support" },
+  { value: "execution", label: "Execution" },
+  { value: "general", label: "General" },
+];
+
+const CREATE_CATEGORY_OPTIONS = CATEGORY_OPTIONS.filter(
+  (item): item is { value: ProposalThreadCategoryDto; label: string } =>
+    item.value !== "all",
+);
+
+const THREAD_STATUS_OPTIONS: Array<
+  DiscussionStatusOption<ProposalThreadDto["status"]>
+> = [
+  { value: "open", label: "Open" },
+  { value: "resolved", label: "Resolved" },
+  { value: "locked", label: "Locked" },
+];
+
+function categoryLabel(value: ProposalThreadCategoryDto): string {
+  return (
+    CREATE_CATEGORY_OPTIONS.find((item) => item.value === value)?.label ??
+    "General"
+  );
+}
+
+function statusLabel(value: ProposalThreadDto["status"]): string {
+  if (value === "resolved") return "Resolved";
+  if (value === "locked") return "Locked";
+  return "Open";
+}
+
+function canAttemptWrite(auth: ReturnType<typeof useAuth>): boolean {
+  if (!auth.enabled) return true;
+  return auth.authenticated && auth.eligible;
+}
+
+type ProposalDeliberationProps = {
+  proposalId: string | undefined;
+};
+
+export const ProposalDeliberation: React.FC<ProposalDeliberationProps> = ({
+  proposalId,
+}) => {
+  const auth = useAuth();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const selectedThreadId = searchParams.get("thread")?.trim() || null;
+  const [threadList, setThreadList] = useState<ProposalThreadListDto | null>(
+    null,
+  );
+  const [activeThread, setActiveThread] =
+    useState<ProposalThreadDetailDto | null>(null);
+  const [listError, setListError] = useState<string | null>(null);
+  const [detailError, setDetailError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [filter, setFilter] = useState<ProposalThreadCategoryDto | "all">(
+    "all",
+  );
+  const [newCategory, setNewCategory] =
+    useState<ProposalThreadCategoryDto>("question");
+  const [newTitle, setNewTitle] = useState("");
+  const [newBody, setNewBody] = useState("");
+  const [replyBody, setReplyBody] = useState("");
+  const detailRef = useRef<HTMLDivElement | null>(null);
+
+  const loadList = useCallback(async () => {
+    if (!proposalId) return;
+    try {
+      const next = await apiProposalThreads(proposalId);
+      setThreadList(next);
+      setListError(null);
+    } catch (error) {
+      setThreadList(null);
+      setListError((error as Error).message);
+    }
+  }, [proposalId]);
+
+  const loadDetail = useCallback(
+    async (threadId: string) => {
+      if (!proposalId || !threadId) return;
+      try {
+        const detail = await apiProposalThreadDetail(proposalId, threadId);
+        setActiveThread(detail);
+        setDetailError(null);
+      } catch (error) {
+        setActiveThread(null);
+        setDetailError((error as Error).message);
+      }
+    },
+    [proposalId],
+  );
+
+  useEffect(() => {
+    void loadList();
+  }, [loadList]);
+
+  useEffect(() => {
+    if (!selectedThreadId) {
+      setActiveThread(null);
+      setDetailError(null);
+      return;
+    }
+    void loadDetail(selectedThreadId);
+  }, [loadDetail, selectedThreadId]);
+
+  const writeAllowed = canAttemptWrite(auth);
+
+  const threadListForViewer = useMemo<ProposalThreadListDto | null>(() => {
+    if (!threadList) return null;
+    if (writeAllowed) return threadList;
+    return {
+      ...threadList,
+      permissions: {
+        ...threadList.permissions,
+        canCreate: false,
+      },
+      items: threadList.items.map((thread) => ({
+        ...thread,
+        permissions: {
+          ...thread.permissions,
+          canReply: false,
+          canTransition: false,
+        },
+      })),
+    };
+  }, [threadList, writeAllowed]);
+
+  const activeThreadForViewer = useMemo<ProposalThreadDetailDto | null>(() => {
+    if (!activeThread) return null;
+    if (writeAllowed) return activeThread;
+    return {
+      ...activeThread,
+      thread: {
+        ...activeThread.thread,
+        permissions: {
+          ...activeThread.thread.permissions,
+          canReply: false,
+          canTransition: false,
+        },
+      },
+      messages: activeThread.messages,
+    };
+  }, [activeThread, writeAllowed]);
+
+  const visibleThreads = useMemo(() => {
+    const items = threadListForViewer?.items ?? [];
+    if (filter === "all") return items;
+    return items.filter((thread) => thread.category === filter);
+  }, [filter, threadListForViewer?.items]);
+
+  const replyCount = useMemo(
+    () =>
+      (threadList?.items ?? []).reduce(
+        (sum, thread) => sum + thread.replies,
+        0,
+      ),
+    [threadList?.items],
+  );
+
+  const canCreate = writeAllowed && Boolean(threadList?.permissions.canCreate);
+  const createDisabledMessage = !writeAllowed
+    ? "Sign in as an active human node to write."
+    : threadList && !threadList.permissions.canCreate
+      ? "Read-only until your session is active."
+      : null;
+
+  const scrollToDetail = useCallback(() => {
+    window.setTimeout(() => {
+      detailRef.current?.scrollIntoView({
+        behavior: "smooth",
+        block: "start",
+      });
+    }, 0);
+  }, []);
+
+  const selectThread = useCallback(
+    (threadId: string) => {
+      const next = new URLSearchParams(searchParams);
+      next.set("thread", threadId);
+      setSearchParams(next, { preventScrollReset: true, replace: true });
+      scrollToDetail();
+    },
+    [scrollToDetail, searchParams, setSearchParams],
+  );
+
+  const createThread = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (!proposalId || !canCreate) return;
+    if (!newTitle.trim() || !newBody.trim()) {
+      setActionError("Thread title and body are required.");
+      return;
+    }
+    setBusy(true);
+    setActionError(null);
+    try {
+      const res = await apiProposalThreadCreate({
+        proposalId,
+        category: newCategory,
+        title: newTitle.trim(),
+        body: newBody.trim(),
+        idempotencyKey: crypto.randomUUID(),
+      });
+      setNewTitle("");
+      setNewBody("");
+      await loadList();
+      selectThread(res.thread.id);
+    } catch (error) {
+      setActionError((error as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const replyToThread = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (!proposalId || !activeThread || !replyBody.trim()) return;
+    if (!writeAllowed || !activeThread.thread.permissions.canReply) return;
+    setBusy(true);
+    setActionError(null);
+    try {
+      await apiProposalThreadReply({
+        proposalId,
+        threadId: activeThread.thread.id,
+        body: replyBody.trim(),
+        idempotencyKey: crypto.randomUUID(),
+      });
+      setReplyBody("");
+      await Promise.all([loadList(), loadDetail(activeThread.thread.id)]);
+    } catch (error) {
+      setActionError((error as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const transitionThread = async (status: ProposalThreadDto["status"]) => {
+    if (!proposalId || !activeThread) return;
+    if (!writeAllowed || !activeThread.thread.permissions.canTransition) return;
+    setBusy(true);
+    setActionError(null);
+    try {
+      await apiProposalThreadTransition({
+        proposalId,
+        threadId: activeThread.thread.id,
+        status,
+        idempotencyKey: crypto.randomUUID(),
+      });
+      await Promise.all([loadList(), loadDetail(activeThread.thread.id)]);
+    } catch (error) {
+      setActionError((error as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  if (!proposalId) return null;
+
+  return (
+    <Surface
+      as="section"
+      variant="panel"
+      radius="xl"
+      shadow="tile"
+      className="p-5"
+    >
+      <header className="flex flex-col gap-2 border-b border-border pb-4 sm:flex-row sm:items-start sm:justify-between">
+        <h2 className="text-lg font-semibold text-text">Deliberation</h2>
+        <div className="flex flex-wrap gap-2 text-xs text-muted">
+          <span>{threadList?.items.length ?? 0} threads</span>
+          <span>{replyCount} replies</span>
+        </div>
+      </header>
+
+      {listError ? (
+        <Surface
+          variant="panelAlt"
+          radius="xl"
+          shadow="none"
+          className="mt-4 px-4 py-3 text-sm text-destructive"
+        >
+          Deliberation unavailable: {formatLoadError(listError)}
+        </Surface>
+      ) : null}
+
+      <ThreadCategoryFilter
+        options={CATEGORY_OPTIONS}
+        value={filter}
+        onChange={setFilter}
+      />
+
+      <ThreadComposer
+        categoryOptions={CREATE_CATEGORY_OPTIONS}
+        categoryValue={newCategory}
+        onCategoryChange={setNewCategory}
+        title={newTitle}
+        onTitleChange={setNewTitle}
+        body={newBody}
+        onBodyChange={setNewBody}
+        onSubmit={createThread}
+        canCreate={canCreate}
+        busy={busy}
+        disabledMessage={createDisabledMessage}
+      />
+
+      {actionError ? (
+        <Surface
+          variant="panelAlt"
+          radius="xl"
+          shadow="none"
+          className="mt-4 px-4 py-3 text-sm text-destructive"
+        >
+          {formatLoadError(actionError)}
+        </Surface>
+      ) : null}
+
+      <div className="mt-5 grid gap-4 lg:grid-cols-[minmax(0,1fr)_minmax(320px,0.9fr)]">
+        <div className="space-y-3">
+          <ThreadList
+            threads={visibleThreads}
+            selectedThreadId={selectedThreadId}
+            emptyMessage="No deliberation threads yet."
+            categoryLabel={categoryLabel}
+            statusLabel={statusLabel}
+            onSelect={selectThread}
+          />
+        </div>
+
+        <div ref={detailRef}>
+          <ThreadDetail
+            detail={activeThreadForViewer}
+            errorText={
+              detailError
+                ? `Thread unavailable: ${formatLoadError(detailError)}`
+                : null
+            }
+            busy={busy}
+            emptyMessage="Open a thread to read the full discussion."
+            categoryLabel={categoryLabel}
+            statusLabel={statusLabel}
+            statusOptions={THREAD_STATUS_OPTIONS}
+            replyBody={replyBody}
+            onReplyBodyChange={setReplyBody}
+            onReply={replyToThread}
+            onTransition={transitionThread}
+            replyPlaceholder={(thread) =>
+              thread.status === "locked" ? "Thread is locked" : "Write a reply"
+            }
+          />
+        </div>
+      </div>
+    </Surface>
+  );
+};
diff --git a/src/pages/proposals/ProposalFinished.tsx b/src/pages/proposals/ProposalFinished.tsx
index 7ae480a..9e87410 100644
--- a/src/pages/proposals/ProposalFinished.tsx
+++ b/src/pages/proposals/ProposalFinished.tsx
@@ -19,6 +19,7 @@ import {
   useProposalTransitionNotice,
 } from "./useProposalStageSync";
 import { formatLoadError } from "@/lib/errorFormatting";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalFinished: React.FC = () => {
   const { id } = useParams();
@@ -186,6 +187,8 @@ const ProposalFinished: React.FC = () => {
         />
       ) : null}
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/ProposalFormation.tsx b/src/pages/proposals/ProposalFormation.tsx
index 3289cd5..35048b4 100644
--- a/src/pages/proposals/ProposalFormation.tsx
+++ b/src/pages/proposals/ProposalFormation.tsx
@@ -26,6 +26,7 @@ import {
   useProposalStageSync,
   useProposalTransitionNotice,
 } from "./useProposalStageSync";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalFormation: React.FC = () => {
   const { id } = useParams();
@@ -332,6 +333,8 @@ const ProposalFormation: React.FC = () => {
         milestonesDetail={project.milestonesDetail}
       />
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/ProposalPP.tsx b/src/pages/proposals/ProposalPP.tsx
index b664e85..426a61a 100644
--- a/src/pages/proposals/ProposalPP.tsx
+++ b/src/pages/proposals/ProposalPP.tsx
@@ -26,6 +26,7 @@ import {
   useProposalStageSync,
   useProposalTransitionNotice,
 } from "./useProposalStageSync";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalPP: React.FC = () => {
   const { id } = useParams();
@@ -297,6 +298,8 @@ const ProposalPP: React.FC = () => {
         />
       ) : null}
 
+      <ProposalDeliberation proposalId={id} />
+
       <Modal
         open={showRules}
         onOpenChange={setShowRules}
diff --git a/src/pages/proposals/ProposalReferendum.tsx b/src/pages/proposals/ProposalReferendum.tsx
index b01f648..8fef22e 100644
--- a/src/pages/proposals/ProposalReferendum.tsx
+++ b/src/pages/proposals/ProposalReferendum.tsx
@@ -29,6 +29,7 @@ import {
 import { useAuth } from "@/app/auth/AuthContext";
 import { apiCitizenVetoVote } from "@/lib/apiClient";
 import { CitizenVetoActions } from "./CitizenVetoActions";
+import { ProposalDeliberation } from "./ProposalDeliberation";
 
 const ProposalReferendum: React.FC = () => {
   const { id } = useParams();
@@ -407,6 +408,8 @@ const ProposalReferendum: React.FC = () => {
         />
       ) : null}
 
+      <ProposalDeliberation proposalId={id} />
+
       {timelineError ? (
         <Surface
           variant="panelAlt"
diff --git a/src/pages/proposals/Proposals.tsx b/src/pages/proposals/Proposals.tsx
index 7951225..514c825 100644
--- a/src/pages/proposals/Proposals.tsx
+++ b/src/pages/proposals/Proposals.tsx
@@ -63,6 +63,12 @@ function hasFinishedRoute(href?: string): boolean {
   return Boolean(href?.includes("/finished"));
 }
 
+const DELIBERATION_STAT_LABELS = new Set([
+  "Deliberation",
+  "Open concerns",
+  "Last discussion",
+]);
+
 const Proposals: React.FC = () => {
   const [proposalData, setProposalData] = useState<
     ProposalListItemDto[] | null
@@ -503,7 +509,7 @@ const Proposals: React.FC = () => {
               proposal.stage === "build" && formationPage
                 ? getFormationProgress(formationPage)
                 : null;
-            const keyStats =
+            const baseKeyStats =
               proposal.stage === "pool" && poolPage && poolStats
                 ? poolPage.formationEligible
                   ? [
@@ -573,6 +579,16 @@ const Proposals: React.FC = () => {
                               ...formationPage.stats,
                             ]
                           : proposal.stats;
+            const deliberationStats = proposal.stats.filter((stat) =>
+              DELIBERATION_STAT_LABELS.has(stat.label),
+            );
+            const keyStats = [
+              ...baseKeyStats,
+              ...deliberationStats.filter(
+                (stat) =>
+                  !baseKeyStats.some((item) => item.label === stat.label),
+              ),
+            ];
 
             return (
               <ExpandableCard
diff --git a/src/types/api.ts b/src/types/api.ts
index 91985a3..999c77f 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -218,6 +218,58 @@ export type ChamberThreadDetailDto = {
   };
   messages: ChamberThreadMessageDto[];
 };
+
+export type ProposalThreadCategoryDto =
+  | "question"
+  | "concern"
+  | "amendment"
+  | "support"
+  | "execution"
+  | "general";
+export type ProposalThreadStatusDto = "open" | "resolved" | "locked";
+export type ProposalThreadPermissionsDto = {
+  canReply: boolean;
+  canTransition: boolean;
+  canDelete: boolean;
+};
+export type ProposalThreadDto = {
+  id: string;
+  proposalId: string;
+  decisionRootProposalId: string;
+  category: ProposalThreadCategoryDto;
+  status: ProposalThreadStatusDto;
+  title: string;
+  body: string;
+  authorAddress: string;
+  replies: number;
+  createdAt: string;
+  updatedAt: string;
+  permissions: ProposalThreadPermissionsDto;
+};
+export type ProposalThreadMessageDto = {
+  id: string;
+  proposalId: string;
+  threadId: string;
+  authorAddress: string;
+  body: string;
+  createdAt: string;
+  updatedAt: string;
+  permissions: {
+    canDelete: boolean;
+  };
+};
+export type ProposalThreadListDto = {
+  proposalId: string;
+  permissions: {
+    canCreate: boolean;
+  };
+  items: ProposalThreadDto[];
+};
+export type ProposalThreadDetailDto = {
+  proposalId: string;
+  thread: ProposalThreadDto;
+  messages: ProposalThreadMessageDto[];
+};
 export type ChamberChatMessageDto = {
   id: string;
   author: string;

From 4c940b1d5d2d1690d2f594d932754bcb859318dc Mon Sep 17 00:00:00 2001
From: Cyber-preacher <davidkavazi@gmail.com>
Date: Wed, 15 Apr 2026 17:25:52 +0400
Subject: [PATCH 2/3] Restore faction thread delete API helpers

---
 src/lib/apiClient.ts | 57 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/src/lib/apiClient.ts b/src/lib/apiClient.ts
index b8e4f3d..ee722bd 100644
--- a/src/lib/apiClient.ts
+++ b/src/lib/apiClient.ts
@@ -1355,6 +1355,63 @@ export async function apiFactionThreadTransition(input: {
   );
 }
 
+export async function apiFactionThreadDelete(input: {
+  factionId: string;
+  threadId: string;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "faction.thread.delete";
+  factionId: string;
+  threadId: string;
+  deleted: true;
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "faction.thread.delete",
+      payload: {
+        factionId: input.factionId,
+        threadId: input.threadId,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
+export async function apiFactionThreadReplyDelete(input: {
+  factionId: string;
+  threadId: string;
+  messageId: string;
+  idempotencyKey?: string;
+}): Promise<{
+  ok: true;
+  type: "faction.thread.reply.delete";
+  factionId: string;
+  threadId: string;
+  messageId: string;
+  deleted: true;
+}> {
+  return await apiPost(
+    "/api/command",
+    {
+      type: "faction.thread.reply.delete",
+      payload: {
+        factionId: input.factionId,
+        threadId: input.threadId,
+        messageId: input.messageId,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    input.idempotencyKey
+      ? { headers: { "idempotency-key": input.idempotencyKey } }
+      : undefined,
+  );
+}
+
 export async function apiFactionInitiativeCreate(input: {
   factionId: string;
   title: string;

From 19d8b86072bbe19e20bc9cf3f325c84916eef9c9 Mon Sep 17 00:00:00 2001
From: Cyber-preacher <davidkavazi@gmail.com>
Date: Wed, 15 Apr 2026 19:20:39 +0400
Subject: [PATCH 3/3] Hide faction thread delete controls

---
 src/pages/factions/FactionChannel.tsx | 83 ++++++---------------------
 1 file changed, 17 insertions(+), 66 deletions(-)

diff --git a/src/pages/factions/FactionChannel.tsx b/src/pages/factions/FactionChannel.tsx
index 626687d..112c4aa 100644
--- a/src/pages/factions/FactionChannel.tsx
+++ b/src/pages/factions/FactionChannel.tsx
@@ -13,8 +13,6 @@ import { Input } from "@/components/primitives/input";
 import { Select } from "@/components/primitives/select";
 import {
   apiFaction,
-  apiFactionThreadDelete,
-  apiFactionThreadReplyDelete,
   apiFactionThreadReply,
   apiFactionThreadTransition,
   apiMe,
@@ -208,27 +206,6 @@ const FactionChannel: React.FC = () => {
                       {formatDateTime(thread.updatedAt)}
                     </p>
                   </Link>
-                  {canModerate ||
-                  normalizeAddress(thread.authorAddress) ===
-                    normalizeAddress(viewerAddress ?? "") ? (
-                    <div className="px-2 py-2">
-                      <Button
-                        size="sm"
-                        variant="outline"
-                        disabled={mutating}
-                        onClick={() =>
-                          runAction(async () => {
-                            await apiFactionThreadDelete({
-                              factionId: faction.id,
-                              threadId: thread.id,
-                            });
-                          })
-                        }
-                      >
-                        Delete
-                      </Button>
-                    </div>
-                  ) : null}
                 </div>
               </div>
             ))
@@ -269,50 +246,24 @@ const FactionChannel: React.FC = () => {
                   {(activeThread.messages ?? []).length === 0 ? (
                     <p className="text-sm text-muted">No replies yet.</p>
                   ) : (
-                    (activeThread.messages ?? []).map((message) => {
-                      const canDeleteMessage =
-                        canModerate ||
-                        normalizeAddress(message.authorAddress) ===
-                          normalizeAddress(viewerAddress ?? "");
-                      return (
-                        <div
-                          key={message.id}
-                          className="space-y-1 rounded-md border border-border px-3 py-2"
-                        >
-                          <div className="flex items-center justify-between gap-2">
-                            <AddressInline
-                              address={message.authorAddress}
-                              className="text-text"
-                              textClassName="text-xs [overflow-wrap:anywhere] break-words"
-                            />
-                            <div className="flex items-center gap-2">
-                              <span className="text-xs text-muted">
-                                {formatDateTime(message.createdAt)}
-                              </span>
-                              {canDeleteMessage ? (
-                                <Button
-                                  size="sm"
-                                  variant="outline"
-                                  disabled={mutating}
-                                  onClick={() =>
-                                    runAction(async () => {
-                                      await apiFactionThreadReplyDelete({
-                                        factionId: faction.id,
-                                        threadId: activeThread.id,
-                                        messageId: message.id,
-                                      });
-                                    })
-                                  }
-                                >
-                                  Delete
-                                </Button>
-                              ) : null}
-                            </div>
-                          </div>
-                          <p className="text-sm text-muted">{message.body}</p>
+                    (activeThread.messages ?? []).map((message) => (
+                      <div
+                        key={message.id}
+                        className="space-y-1 rounded-md border border-border px-3 py-2"
+                      >
+                        <div className="flex items-center justify-between gap-2">
+                          <AddressInline
+                            address={message.authorAddress}
+                            className="text-text"
+                            textClassName="text-xs [overflow-wrap:anywhere] break-words"
+                          />
+                          <span className="text-xs text-muted">
+                            {formatDateTime(message.createdAt)}
+                          </span>
                         </div>
-                      );
-                    })
+                        <p className="text-sm text-muted">{message.body}</p>
+                      </div>
+                    ))
                   )}
                 </div>