@multiplatform.one/components 6.1.0 → 6.4.0

package/src/layouts/timeline.tsx

@@ -1,30 +1,49 @@
 import {
+  ArrowBendUpLeftIcon,
+  ArrowBendUpRightIcon,
+  ChatCircleIcon,
   ClockIcon,
-  PencilSimpleIcon,
   FileTextIcon,
-  ChatCircleIcon,
-  PaperclipIcon,
-  PlusIcon,
   PaperPlaneTiltIcon,
-  UserPlusIcon,
+  PaperclipIcon,
+  PencilSimpleIcon,
   UserIcon,
+  UserPlusIcon,
 } from "@phosphor-icons/react";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
-import React, { useCallback, useState } from "react";
+import { useDirection } from "../hooks/useDirection";
+import {
+  MIN_PRESS_TARGET,
+  formatAbsoluteDateTime,
+  formatRelativeTimestamp,
+  pressTargetHitSlop,
+  pressTargetStyle,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import React, { useCallback, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
 import {
-  Avatar,
   Button,
+  H2,
+  H3,
   H4,
-  ListItem,
-  Separator,
+  H5,
+  H6,
   Spinner,
   Text,
   TextArea,
   XStack,
   YStack,
   type YStackProps,
+  isWeb,
 } from "tamagui";
-import { componentColors } from "../componentColors";
+import { Avatar } from "../Avatar";
+import { componentColors, sectionHeading } from "../componentColors";
+import { bidiIsolate } from "../shared/t";
+import { Skeleton } from "../Skeleton";
+import { AsyncBoundary, resolveAsyncStatus } from "./AsyncBoundary";
+
+/** Semantic label level → tamagui heading component (runtime `tag` is not honored). */
+const TIMELINE_HEADING_TAGS = { 2: H2, 3: H3, 4: H4, 5: H5, 6: H6 } as const;
 
 // ---------------------------------------------------------------------------
 // Types  (generic -- no Frappe dependency)
@@ -41,7 +60,8 @@ export interface VersionChange {
 }
 
 /**
- * Timeline entry type
+ * Timeline entry kind. `comment` renders as a conversation entry (avatar,
+ * display name, body, Reply); the rest render as compact system/event rows.
  */
 export type TimelineEntryType = "comment" | "version" | "attachment" | "assignment" | "info";
 
@@ -52,43 +72,88 @@ export type TimelineEntryType = "comment" | "version" | "attachment" | "assignme
 export interface TimelineEntry {
   /** Unique identifier */
   id: string;
-  /** Entry type */
+  /** Entry kind: `comment` vs system/event types */
   type: TimelineEntryType;
   /** Text content (comment text, info message, etc.) */
   content?: string;
-  /** Author display name or email */
+  /** Author identifier -- display name or email (legacy). Never rendered raw
+   * when it is an email: the local part is prettified ("john.doe@x" -> "John Doe"). */
   author: string;
+  /** Explicit author display name -- preferred over `author` when present */
+  authorName?: string;
   /** Author email */
   authorEmail?: string;
   /** ISO timestamp string */
   timestamp: string;
+  /** Parent entry id -- replies nest one level under their thread root */
+  parentId?: string;
   /** For version entries, the changes made */
   changes?: VersionChange[];
 }
 
+/** A top-level entry with its (flattened, one-level) replies. */
+export interface TimelineThread {
+  entry: TimelineEntry;
+  replies: TimelineEntry[];
+}
+
 export interface TimelineProps extends Omit<YStackProps, "children"> {
   /** Timeline entries to display */
   entries: TimelineEntry[];
 
   /** Label for the timeline section */
   label?: string;
+  /**
+   * Semantic level of the label heading (DG-A11Y-02). Default 2 — catalog
+   * section labels sit one step below the page h1 (see `sectionHeading`).
+   * Only the tag / aria-level changes; the visual scale stays the same.
+   */
+  headingLevel?: 2 | 3 | 4 | 5 | 6;
   /** Whether interactions are disabled (read-only) */
   disabled?: boolean;
 
-  /** Whether to allow adding new comments */
+  /** Whether entries are loading — renders a row-shaped skeleton twin (LC-20 / DG-ST-02) */
+  isLoading?: boolean;
+  /**
+   * Failed load (DG-ST-01 / Axiom 6). Wins over the empty chrome so a failed
+   * feed never masquerades as "no activity"; the composer and entry count
+   * hide while set (DG-ST-04). Pass a string, Error, custom node, or `true`
+   * for the default error UI.
+   */
+  error?: boolean | string | Error | React.ReactNode | null;
+  /** Retry handler for the default error chrome */
+  onRetry?: () => void;
+
+  /** Whether to show the inline comment composer (default true) */
   enableAddComment?: boolean;
 
-  /** Called when a comment is added */
+  /** Called when a top-level comment is added (legacy -- prefer onCommentSubmit) */
   onCommentAdded?: (content: string) => void;
+  /** Called when a comment or reply is submitted */
+  onCommentSubmit?: (content: string, options?: { parentId?: string }) => void;
+  /** Called when Reply is pressed on a comment. When omitted, an inline reply
+   * composer opens under that comment instead. */
+  onReply?: (entry: TimelineEntry) => void;
   /** Called when a timeline entry is clicked */
   onEntryClick?: (entry: TimelineEntry) => void;
 
+  /** Controlled composer value */
+  commentValue?: string;
+  /** Uncontrolled composer initial value */
+  defaultCommentValue?: string;
+  /** Called when the composer value changes */
+  onCommentChange?: (content: string) => void;
+
   /** Custom empty state renderer */
   renderEmpty?: () => React.ReactNode;
   /** Custom entry renderer */
   renderEntry?: (entry: TimelineEntry, defaultContent: React.ReactNode) => React.ReactNode;
 
-  /** Optional function to format timestamps for display */
+  /** Optional function to format the visible timestamp — the per-use eject
+   * for every entry class. When omitted, the content class picks the register
+   * (LC-12): comment rows render the relative form ("2h ago"); system events
+   * follow the house `timestampStyle` knob (compact absolute by default).
+   * The absolute compact timestamp always sits in the tooltip. */
   formatTimestamp?: (timestamp: string) => string;
 
   /** Compact mode - smaller UI */
@@ -101,15 +166,19 @@ export interface TimelineProps extends Omit<YStackProps, "children"> {
     cancel?: string;
     comment?: string;
     sending?: string;
+    reply?: string;
     madeChanges?: string;
     addedAttachment?: string;
     assigned?: string;
     empty?: string;
     entry?: string;
     entries?: string;
+    loadFailed?: string;
   };
   /** Placeholder text for new comment input */
   placeholder?: string;
+  /** Placeholder text for the inline reply composer */
+  replyPlaceholder?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -133,24 +202,89 @@ function getEntryIcon(entry: TimelineEntry, size: number): React.ReactNode {
   }
 }
 
-function getInitials(name: string): string {
-  const parts = name.split(/[\s@]/);
-  if (parts.length >= 2) {
-    return (parts[0][0] + parts[1][0]).toUpperCase();
-  }
-  return name.substring(0, 2).toUpperCase();
+/**
+ * Derive a human display name. Non-emails pass through untouched; emails get
+ * their local part split on separators and title-cased ("john.doe@x" -> "John Doe").
+ * A raw email is never returned as a display name.
+ */
+export function prettifyAuthorName(raw: string): string {
+  const name = (raw ?? "").trim();
+  if (!name) return "Unknown";
+  if (!name.includes("@")) return name;
+  const local = name.split("@")[0];
+  const words = local.split(/[._+\-\d]+/).filter(Boolean);
+  if (words.length === 0) return local || "Unknown";
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
 }
 
+/** Display name for an entry: explicit authorName, else prettified author. */
+export function getEntryDisplayName(entry: Pick<TimelineEntry, "author" | "authorName">): string {
+  return entry.authorName?.trim() || prettifyAuthorName(entry.author);
+}
+
+/**
+ * Compact absolute timestamp ("Aug 9, 3:30 PM"; adds year when not current).
+ * Canonical formatter lives in theme (LC-12 / DF-14): one register for
+ * Timeline, table date cells, and picker display values.
+ */
 function defaultFormatTimestamp(timestamp: string): string {
-  try {
-    return new Date(timestamp).toLocaleString();
-  } catch {
-    return timestamp;
-  }
+  return formatAbsoluteDateTime(timestamp);
 }
 
-function getEntrySubTitle(entry: TimelineEntry, formatTimestamp: (ts: string) => string): string {
-  return formatTimestamp(entry.timestamp);
+// Relative register re-exported so existing consumers keep their import path.
+export { formatRelativeTimestamp } from "@multiplatform.one/theme";
+
+/**
+ * Group a flat entry list into one-level threads. Top-level order follows the
+ * input order of the root entries; replies (including reply-to-reply, which
+ * flattens under the thread root) sort oldest-first so threads read downward.
+ * Orphaned parentIds (parent missing from the list) fall back to top-level.
+ */
+export function threadEntries(entries: TimelineEntry[]): TimelineThread[] {
+  const byId = new Map(entries.map((e) => [e.id, e]));
+
+  const rootOf = (entry: TimelineEntry): TimelineEntry => {
+    let current = entry;
+    const seen = new Set<string>([current.id]);
+    while (current.parentId) {
+      const parent = byId.get(current.parentId);
+      if (!parent || seen.has(parent.id)) break;
+      seen.add(parent.id);
+      current = parent;
+    }
+    return current;
+  };
+
+  const threads: TimelineThread[] = [];
+  const threadByRootId = new Map<string, TimelineThread>();
+  for (const entry of entries) {
+    if (rootOf(entry).id !== entry.id) continue;
+    const thread: TimelineThread = { entry, replies: [] };
+    threads.push(thread);
+    threadByRootId.set(entry.id, thread);
+  }
+  for (const entry of entries) {
+    const root = rootOf(entry);
+    if (root.id === entry.id) continue;
+    const thread = threadByRootId.get(root.id);
+    if (thread) {
+      thread.replies.push(entry);
+    } else {
+      // parentId cycle: no resolvable root — promote to top-level so no
+      // entry ever silently disappears from the feed
+      const fallback: TimelineThread = { entry, replies: [] };
+      threads.push(fallback);
+      threadByRootId.set(entry.id, fallback);
+    }
+  }
+  const time = (e: TimelineEntry) => {
+    const t = new Date(e.timestamp).getTime();
+    return Number.isNaN(t) ? 0 : t;
+  };
+  for (const thread of threads) {
+    thread.replies.sort((a, b) => time(a) - time(b));
+  }
+  return threads;
 }
 
 function getEntryActionLabel(
@@ -163,78 +297,180 @@ function getEntryActionLabel(
   return undefined;
 }
 
+/**
+ * Skeleton twin of the comment rows (LC-20 / DG-ST-02): avatar block +
+ * name/time line + body line mirror the live entry anatomy. The avatar
+ * follows the radius knob like the live Avatar (no hardcoded circle).
+ */
+function TimelineSkeleton({
+  compact,
+  avatarPx,
+  loadingLabel,
+}: {
+  compact: boolean;
+  avatarPx: number;
+  loadingLabel: string;
+}) {
+  return (
+    <YStack
+      gap={compact ? "$3" : "$4"}
+      width="100%"
+      data-async-skeleton="timeline"
+      aria-busy
+      aria-label={loadingLabel}
+    >
+      {Array.from({ length: 3 }).map((_, i) => (
+        <XStack key={i} gap={compact ? "$2" : "$3"} alignItems="flex-start">
+          <Skeleton variant="rounded" width={avatarPx} height={avatarPx} />
+          <YStack flex={1} gap="$1.5" paddingTop={2}>
+            <Skeleton width="35%" height={compact ? 10 : 12} />
+            <Skeleton width="80%" height={compact ? 12 : 14} />
+          </YStack>
+        </XStack>
+      ))}
+    </YStack>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
 
 /**
- * Generic Timeline component for displaying activity entries and comments.
- * Uses Tamagui `ListItem` for each entry with native hover/press animations.
+ * Timeline: a mixed activity feed in the GitHub/Linear mold. Comment entries
+ * render as conversation (avatar, bold display name, relative time, body,
+ * Reply, one-level threaded replies); system events (version/attachment/
+ * assignment/info) render as compact muted single-line rows. An inline
+ * composer sits at the top of the feed.
  * Fully data-agnostic -- accepts entries via props and emits callbacks.
  */
 export function Timeline({
   entries,
   label,
+  headingLevel = 2,
   disabled = false,
+  isLoading = false,
+  error = null,
+  onRetry,
   enableAddComment = true,
   onCommentAdded,
+  onCommentSubmit,
+  onReply,
   onEntryClick,
+  commentValue,
+  defaultCommentValue = "",
+  onCommentChange,
   renderEmpty,
   renderEntry,
-  formatTimestamp = defaultFormatTimestamp,
+  formatTimestamp,
   compact = false,
   labels = {},
-  placeholder = "Add a comment...",
+  placeholder: placeholderProp,
+  replyPlaceholder: replyPlaceholderProp,
   ...stackProps
 }: TimelineProps) {
+  const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
-
-  const [commentText, setCommentText] = useState("");
+  const LabelTag = TIMELINE_HEADING_TAGS[headingLevel];
+  // Reply arrow bends back toward the quoted message — direction-of-travel,
+  // so the glyph pair swaps under RTL (Axiom 15 / useDirection pattern).
+  const ReplyIcon = useDirection() === "rtl" ? ArrowBendUpRightIcon : ArrowBendUpLeftIcon;
+  const placeholder = placeholderProp ?? t("Add a comment...");
+  const replyPlaceholder = replyPlaceholderProp ?? t("Write a reply...");
+
+  const [internalValue, setInternalValue] = useState(defaultCommentValue);
+  const [composerFocused, setComposerFocused] = useState(false);
   const [isAddingComment, setIsAddingComment] = useState(false);
-  const [showCommentInput, setShowCommentInput] = useState(false);
+  const [replyTarget, setReplyTarget] = useState<{ rootId: string; parentId: string } | null>(null);
+  const [replyText, setReplyText] = useState("");
+
+  const composerText = commentValue !== undefined ? commentValue : internalValue;
 
   const {
-    noActivity: noActivityLabel = "No activity yet",
-    addComment: addCommentLabel = "Add Comment",
-    cancel: cancelLabel = "Cancel",
-    comment: commentLabel = "Comment",
-    sending: sendingLabel = "Sending...",
-    madeChanges: madeChangesLabel = "made changes",
-    addedAttachment: addedAttachmentLabel = "added an attachment",
-    assigned: assignedLabel = "assigned",
-    entry: entryLabel = "entry",
-    entries: entriesLabel = "entries",
+    noActivity: noActivityLabel = t("No activity yet"),
+    addComment: addCommentLabel = t("Add Comment"),
+    cancel: cancelLabel = t("Cancel"),
+    comment: commentLabel = t("Comment"),
+    sending: sendingLabel = t("Sending..."),
+    reply: replyLabel = t("Reply"),
+    madeChanges: madeChangesLabel = t("made changes"),
+    addedAttachment: addedAttachmentLabel = t("added an attachment"),
+    assigned: assignedLabel = t("assigned"),
+    entry: entryLabel = t("entry"),
+    entries: entriesLabel = t("entries"),
+    loadFailed: loadFailedLabel = t("Couldn't load activity"),
   } = labels;
 
-  const handleAddComment = useCallback(async () => {
-    const content = commentText.trim();
-    if (!content || isAddingComment) return;
+  // Error wins (DG-ST-01): a failed feed must never look like "no activity".
+  const hasError = resolveAsyncStatus({ error }) === "error";
+  const showSkeleton = !hasError && isLoading && entries.length === 0;
 
-    setIsAddingComment(true);
+  const threads = useMemo(() => threadEntries(entries), [entries]);
+
+  const submitComment = useCallback(
+    (content: string, parentId?: string) => {
+      if (onCommentSubmit) onCommentSubmit(content, parentId ? { parentId } : undefined);
+      else onCommentAdded?.(content);
+    },
+    [onCommentSubmit, onCommentAdded],
+  );
+
+  const canCompose = enableAddComment && !disabled && !!(onCommentSubmit || onCommentAdded);
+  const showReplyAction = !disabled && (!!onReply || canCompose);
 
+  const setComposerText = useCallback(
+    (text: string) => {
+      if (commentValue === undefined) setInternalValue(text);
+      onCommentChange?.(text);
+    },
+    [commentValue, onCommentChange],
+  );
+
+  const handleAddComment = useCallback(() => {
+    const content = composerText.trim();
+    if (!content || isAddingComment) return;
+    setIsAddingComment(true);
     try {
-      onCommentAdded?.(content);
-      setCommentText("");
-      setShowCommentInput(false);
+      submitComment(content);
+      setComposerText("");
+      setComposerFocused(false);
     } finally {
       setIsAddingComment(false);
     }
-  }, [commentText, isAddingComment, onCommentAdded]);
-
-  const handleKeyPress = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (e.key === "Enter" && !e.shiftKey) {
-        e.preventDefault();
-        handleAddComment();
-      } else if (e.key === "Escape") {
-        setShowCommentInput(false);
-        setCommentText("");
+  }, [composerText, isAddingComment, submitComment, setComposerText]);
+
+  const handleSubmitReply = useCallback(() => {
+    const content = replyText.trim();
+    if (!content || !replyTarget) return;
+    submitComment(content, replyTarget.parentId);
+    setReplyText("");
+    setReplyTarget(null);
+  }, [replyText, replyTarget, submitComment]);
+
+  const handleReplyPress = useCallback(
+    (entry: TimelineEntry, rootId: string) => {
+      if (onReply) {
+        onReply(entry);
+        return;
       }
+      if (!canCompose) return;
+      setReplyTarget({ rootId, parentId: entry.id });
+      setReplyText("");
     },
-    [handleAddComment],
+    [onReply, canCompose],
   );
 
   const sz = knobProps.sizeToken;
+  const radiusToken = knobProps.borderRadius.borderRadius;
+  const mutedColor =
+    knobProps.textAccentColor === "$color" ? "$color12" : knobProps.textAccentColor;
+  const bodyFontSize = compact ? "$2" : sz === "$3" ? "$2" : sz === "$5" ? "$4" : "$3";
+  const nameFontSize = compact ? "$2" : sz === "$3" ? "$2" : sz === "$5" ? "$4" : "$3";
+  const metaFontSize = compact ? "$1" : "$2";
+  const systemFontSize = compact ? "$1" : "$2";
+  const avatarSize = compact ? "$1.5" : sz === "$5" ? "$3" : "$2";
+  const replyAvatarSize = compact ? "$1" : "$1.5";
+
   const emptyIconSize = compact
     ? sz === "$3"
       ? 20
@@ -262,6 +498,45 @@ export function Timeline({
     </YStack>
   );
 
+  // LC-12 TIMESTAMP-REGISTER: the content class picks the register.
+  // Social/comment rows default to the relative form ("2h ago"); system
+  // events follow the house `timestampStyle` knob (compact absolute by
+  // default; a house flip to "relative" re-registers events too). A consumer
+  // `formatTimestamp` is the eject for every class.
+  const formatVisibleTimestamp = (entry: TimelineEntry) => {
+    if (formatTimestamp) return formatTimestamp(entry.timestamp);
+    if (entry.type === "comment" || knobProps.timestampStyle === "relative") {
+      return formatRelativeTimestamp(entry.timestamp);
+    }
+    return defaultFormatTimestamp(entry.timestamp);
+  };
+
+  const renderTimestamp = (entry: TimelineEntry, fontSize: string) => (
+    <Text
+      fontSize={fontSize}
+      color={mutedColor}
+      // Absolute compact timestamp in the tooltip + accessible name
+      {...({ title: defaultFormatTimestamp(entry.timestamp) } as Record<string, unknown>)}
+      aria-label={defaultFormatTimestamp(entry.timestamp)}
+    >
+      {formatVisibleTimestamp(entry)}
+    </Text>
+  );
+
+  // Axiom 1 R-SCALE / Axiom 3 NULL: avatars are square at radius:none and a
+  // circle at radius:full — they follow the one radius channel, not a
+  // hardcoded `circular` eject (DF-08). A token exceeding half the box still
+  // renders a circle at the top knob.
+  const renderAvatar = (entry: TimelineEntry, size: string) => (
+    <Avatar
+      circular={false}
+      borderRadius={radiusToken}
+      size={size as any}
+      name={getEntryDisplayName(entry)}
+      fallbackBackgroundColor="$accentBackground"
+    />
+  );
+
   const renderVersionChanges = (changes: VersionChange[]) => (
     <YStack gap="$1" marginTop="$1">
       {changes.slice(0, 5).map((change) => (
@@ -280,7 +555,7 @@ export function Timeline({
           )}
           {change.old !== undefined && change.new !== undefined && (
             <Text fontSize="$1" color={componentColors.text.muted}>
-              {"\u2192"}
+              {"→"}
             </Text>
           )}
           {change.new !== undefined && (
@@ -298,211 +573,375 @@ export function Timeline({
     </YStack>
   );
 
-  const renderTimelineEntry = (entry: TimelineEntry) => {
-    const sz = knobProps.sizeToken;
-    const iconSize = compact ? 14 : sz === "$3" ? 14 : sz === "$5" ? 18 : 16;
-    const containerSize = compact
-      ? sz === "$3"
-        ? 20
-        : sz === "$5"
-          ? 28
-          : 24
-      : sz === "$3"
-        ? 24
-        : sz === "$5"
-          ? 40
-          : 32;
-
-    const entryIcon =
-      entry.type === "comment" ? (
+  const renderComposerBox = ({
+    value,
+    onChange,
+    onSubmit,
+    onCancel,
+    placeholder: composerPlaceholder,
+    autoFocus,
+    expanded,
+    onFocus,
+    onBlur,
+    ariaLabel,
+    avatar,
+  }: {
+    value: string;
+    onChange: (text: string) => void;
+    onSubmit: () => void;
+    onCancel: () => void;
+    placeholder: string;
+    autoFocus?: boolean;
+    expanded: boolean;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    ariaLabel: string;
+    avatar: React.ReactNode;
+  }) => (
+    <XStack {...knobProps.gap} alignItems="flex-start">
+      {avatar}
+      <YStack flex={1} gap="$2">
+        <TextArea
+          value={value}
+          onChangeText={onChange}
+          placeholder={composerPlaceholder}
+          aria-label={ariaLabel}
+          size={compact ? "$2" : "$3"}
+          minHeight={expanded ? (compact ? 60 : 80) : compact ? 32 : 40}
+          backgroundColor={knobProps.inputBackground}
+          {...{ borderRadius: radiusToken }}
+          autoFocus={autoFocus}
+          onFocus={onFocus}
+          onBlur={onBlur}
+          onKeyDown={
+            ((e: React.KeyboardEvent) => {
+              if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault();
+                onSubmit();
+              } else if (e.key === "Escape") {
+                onCancel();
+              }
+            }) as unknown as () => void
+          }
+        />
+        {expanded && (
+          <XStack {...knobProps.gap} justifyContent="flex-end">
+            <Button
+              size={compact ? "$2" : "$3"}
+              variant="outlined"
+              borderRadius={radiusToken}
+              onPress={onCancel}
+              disabled={isAddingComment}
+            >
+              {cancelLabel}
+            </Button>
+            <Button
+              size={compact ? "$2" : "$3"}
+              borderRadius={radiusToken}
+              icon={isAddingComment ? <Spinner size="small" /> : <PaperPlaneTiltIcon size={14} />}
+              onPress={onSubmit}
+              disabled={!value.trim() || isAddingComment}
+            >
+              {isAddingComment ? sendingLabel : commentLabel}
+            </Button>
+          </XStack>
+        )}
+      </YStack>
+    </XStack>
+  );
+
+  const renderComposer = () => {
+    if (!canCompose) return null;
+    const expanded = composerFocused || composerText.trim().length > 0;
+    return renderComposerBox({
+      value: composerText,
+      onChange: setComposerText,
+      onSubmit: handleAddComment,
+      onCancel: () => {
+        setComposerText("");
+        setComposerFocused(false);
+      },
+      placeholder,
+      expanded,
+      onFocus: () => setComposerFocused(true),
+      onBlur: () => {
+        if (!composerText.trim()) setComposerFocused(false);
+      },
+      ariaLabel: addCommentLabel,
+      avatar: (
         <Avatar
-          circular
-          size={compact ? "$1.5" : "$2"}
+          circular={false}
+          borderRadius={radiusToken}
+          size={avatarSize}
           backgroundColor={componentColors.interactive.hover}
         >
-          <Avatar.Fallback backgroundColor={componentColors.interactive.hover}>
-            <Text fontSize="$1" color="$accentColor" fontWeight="600">
-              {getInitials(entry.author)}
-            </Text>
+          <Avatar.Fallback
+            backgroundColor={componentColors.interactive.hover}
+            alignItems="center"
+            justifyContent="center"
+          >
+            <UserIcon size={compact ? 12 : 14} />
           </Avatar.Fallback>
         </Avatar>
-      ) : (
-        <YStack
-          width={containerSize}
-          height={containerSize}
-          borderRadius="$10"
-          backgroundColor={
-            entry.type === "version" ? "$orange4" : componentColors.surface.background
-          }
-          alignItems="center"
-          justifyContent="center"
+      ),
+    });
+  };
+
+  const renderReplyComposer = (parentEntry: TimelineEntry) =>
+    renderComposerBox({
+      value: replyText,
+      onChange: setReplyText,
+      onSubmit: handleSubmitReply,
+      onCancel: () => {
+        setReplyText("");
+        setReplyTarget(null);
+      },
+      placeholder: replyPlaceholder,
+      autoFocus: true,
+      expanded: true,
+      ariaLabel: `${replyLabel} ${getEntryDisplayName(parentEntry)}`,
+      avatar: (
+        <Avatar
+          circular={false}
+          borderRadius={radiusToken}
+          size={replyAvatarSize}
+          backgroundColor={componentColors.interactive.hover}
         >
-          {getEntryIcon(entry, iconSize)}
+          <Avatar.Fallback
+            backgroundColor={componentColors.interactive.hover}
+            alignItems="center"
+            justifyContent="center"
+          >
+            <UserIcon size={compact ? 10 : 12} />
+          </Avatar.Fallback>
+        </Avatar>
+      ),
+    });
+
+  /** Conversation entry: avatar + bold name + relative time + body + Reply. */
+  const renderCommentEntry = (entry: TimelineEntry, rootId: string, isReply: boolean) => {
+    const displayName = getEntryDisplayName(entry);
+    return (
+      <XStack
+        role="article"
+        aria-label={`${displayName}, ${formatVisibleTimestamp(entry)}`}
+        gap={compact ? "$2" : "$3"}
+        alignItems="flex-start"
+        borderRadius={radiusToken}
+        onPress={onEntryClick ? () => onEntryClick(entry) : undefined}
+        cursor={onEntryClick ? "pointer" : "default"}
+      >
+        {renderAvatar(entry, isReply ? replyAvatarSize : avatarSize)}
+        <YStack flex={1} gap="$1">
+          <XStack gap="$2" alignItems="center" flexWrap="wrap">
+            <Text fontSize={nameFontSize} fontWeight="600" color={componentColors.text.primary}>
+              {displayName}
+            </Text>
+            {renderTimestamp(entry, metaFontSize)}
+          </XStack>
+          {entry.content && (
+            <Text
+              {...knobProps.body}
+              fontSize={bodyFontSize}
+              color={componentColors.text.primary}
+              whiteSpace="pre-wrap"
+            >
+              {entry.content}
+            </Text>
+          )}
+          {showReplyAction && (
+            <XStack marginInlineStart={-8}>
+              {/* DG-LAY-04 / D-02 press-floor: the chromeless pill paints at
+                  the $1/$2 token (20/28px) but the press box is floored at 44
+                  via the house pressTarget* channel (grown transparent box +
+                  negative outset + hitSlop) — layout height stays token-sized. */}
+              <Button
+                chromeless
+                size={compact ? "$1" : "$2"}
+                {...pressTargetStyle()}
+                marginVertical={-Math.ceil((MIN_PRESS_TARGET - (compact ? 20 : 28)) / 2)}
+                hitSlop={pressTargetHitSlop(compact ? 20 : 28)}
+                borderRadius={radiusToken}
+                opacity={0.8}
+                icon={<ReplyIcon size={compact ? 10 : 12} />}
+                aria-label={`${replyLabel} ${displayName}`}
+                onPress={(e) => {
+                  (e as unknown as { stopPropagation?: () => void }).stopPropagation?.();
+                  handleReplyPress(entry, rootId);
+                }}
+              >
+                {replyLabel}
+              </Button>
+            </XStack>
+          )}
         </YStack>
-      );
+      </XStack>
+    );
+  };
 
-    const subTitle = getEntrySubTitle(entry, formatTimestamp);
+  /** System/event entry: compact, muted, icon-led single-line row. */
+  const renderSystemEntry = (entry: TimelineEntry) => {
+    const displayName = getEntryDisplayName(entry);
     const actionLabel = getEntryActionLabel(entry, {
       madeChanges: madeChangesLabel,
       addedAttachment: addedAttachmentLabel,
       assigned: assignedLabel,
     });
-
-    const defaultContent = (
-      <ListItem
-        key={entry.id}
-        title={entry.author}
-        subTitle={subTitle}
-        icon={entryIcon}
-        size={compact ? "$3" : knobProps.sizeToken}
-        hoverStyle={{ backgroundColor: componentColors.surface.background }}
-        pressStyle={{ backgroundColor: componentColors.interactive.background }}
-        onPress={() => onEntryClick?.(entry)}
+    const iconSize = compact ? 12 : 14;
+    const discSize = compact ? 20 : 24;
+    return (
+      <XStack
+        role="article"
+        aria-label={`${displayName} ${actionLabel ?? entry.content ?? ""}`.trim()}
+        gap={compact ? "$2" : "$3"}
+        alignItems="flex-start"
+        borderRadius={radiusToken}
+        onPress={onEntryClick ? () => onEntryClick(entry) : undefined}
         cursor={onEntryClick ? "pointer" : "default"}
       >
-        {actionLabel && (
-          <Text fontSize={compact ? "$1" : "$2"} color={componentColors.text.muted} marginTop="$1">
-            {actionLabel}
-          </Text>
-        )}
-
-        {entry.content && entry.type === "comment" && (
-          <Text
-            fontSize={compact ? "$2" : knobProps.sizeToken}
-            color={componentColors.text.muted}
-            marginTop="$1"
-            whiteSpace="pre-wrap"
-          >
-            {entry.content}
-          </Text>
-        )}
-
-        {entry.content && entry.type === "info" && (
-          <Text
-            fontSize={compact ? "$1" : "$2"}
-            color={componentColors.text.muted}
-            fontStyle="italic"
-          >
-            {entry.content}
-          </Text>
-        )}
-
-        {entry.type === "version" &&
-          entry.changes &&
-          entry.changes.length > 0 &&
-          renderVersionChanges(entry.changes)}
-      </ListItem>
+        <YStack
+          width={discSize}
+          height={discSize}
+          alignItems="center"
+          justifyContent="center"
+          opacity={0.6}
+        >
+          {getEntryIcon(entry, iconSize)}
+        </YStack>
+        <YStack flex={1} gap="$0.5" paddingTop={2}>
+          <XStack gap="$1.5" alignItems="center" flexWrap="wrap">
+            <Text fontSize={systemFontSize} fontWeight="600" color={mutedColor}>
+              {displayName}
+            </Text>
+            {actionLabel && (
+              <Text fontSize={systemFontSize} color={mutedColor}>
+                {actionLabel}
+              </Text>
+            )}
+            {entry.content && entry.type !== "info" && (
+              <Text fontSize={systemFontSize} color={mutedColor}>
+                {entry.content}
+              </Text>
+            )}
+            <Text fontSize={systemFontSize} color={mutedColor} opacity={0.75}>
+              {"·"}
+            </Text>
+            {renderTimestamp(entry, systemFontSize)}
+          </XStack>
+          {entry.content && entry.type === "info" && (
+            <Text fontSize={systemFontSize} color={mutedColor} fontStyle="italic">
+              {entry.content}
+            </Text>
+          )}
+          {entry.type === "version" &&
+            entry.changes &&
+            entry.changes.length > 0 &&
+            renderVersionChanges(entry.changes)}
+        </YStack>
+      </XStack>
     );
+  };
 
-    if (renderEntry) {
-      return renderEntry(entry, defaultContent);
-    }
-
+  const renderEntryNode = (entry: TimelineEntry, rootId: string, isReply: boolean) => {
+    const defaultContent =
+      entry.type === "comment"
+        ? renderCommentEntry(entry, rootId, isReply)
+        : renderSystemEntry(entry);
+    if (renderEntry) return renderEntry(entry, defaultContent);
     return defaultContent;
   };
 
-  const renderCommentInput = () => {
-    if (!enableAddComment || disabled || !onCommentAdded) return null;
-
-    if (!showCommentInput) {
-      return (
-        <Button
-          size={compact ? "$3" : "$4"}
-          variant="outlined"
-          icon={<PlusIcon size={compact ? 14 : 16} />}
-          onPress={() => setShowCommentInput(true)}
-          alignSelf="flex-start"
-        >
-          {addCommentLabel}
-        </Button>
-      );
-    }
-
+  const renderThread = (thread: TimelineThread) => {
+    const rootId = thread.entry.id;
+    const hasThreadTail =
+      thread.replies.length > 0 || (replyTarget && replyTarget.rootId === rootId);
     return (
-      <YStack
-        {...knobProps.gap}
-        {...(compact ? { padding: "$2" } : knobProps.panelPadding)}
-        {...{ backgroundColor: componentColors.surface.background }}
-        {...knobProps.borderRadius}
-        borderColor="$borderColor"
-      >
-        <XStack {...knobProps.gap} alignItems="flex-start">
-          <Avatar
-            circular
-            size={compact ? "$1.5" : "$2"}
-            backgroundColor={componentColors.interactive.hover}
+      <YStack key={rootId} gap={compact ? "$2" : "$3"}>
+        {renderEntryNode(thread.entry, rootId, false)}
+        {hasThreadTail && (
+          // Avatar-inset: replies indent by the parent avatar column width.
+          // Logical start rail so the thread indent mirrors in RTL; tamagui
+          // borderStartWidth does not compile to working CSS on web (SB-M-1215).
+          <YStack
+            marginInlineStart={compact ? 28 : sz === "$5" ? 46 : 36}
+            gap={compact ? "$2" : "$3"}
+            paddingInlineStart={compact ? "$2" : "$3"}
+            {...(isWeb
+              ? {
+                  borderInlineStartWidth: 1,
+                  borderInlineStartStyle: "solid" as any,
+                  borderInlineStartColor: componentColors.divider,
+                }
+              : { borderStartWidth: 1, borderStartColor: componentColors.divider })}
           >
-            <Avatar.Fallback backgroundColor={componentColors.interactive.hover}>
-              <UserIcon size={compact ? 12 : 14} />
-            </Avatar.Fallback>
-          </Avatar>
-          <YStack flex={1} {...knobProps.gap}>
-            <TextArea
-              value={commentText}
-              onChangeText={setCommentText}
-              placeholder={placeholder}
-              size={compact ? "$2" : "$3"}
-              minHeight={compact ? 60 : 80}
-              autoFocus
-              onKeyDown={handleKeyPress as unknown as () => void}
-            />
-            <XStack {...knobProps.gap} justifyContent="flex-end">
-              <Button
-                size={compact ? "$2" : "$3"}
-                variant="outlined"
-                onPress={() => {
-                  setShowCommentInput(false);
-                  setCommentText("");
-                }}
-                disabled={isAddingComment}
-              >
-                {cancelLabel}
-              </Button>
-              <Button
-                size={compact ? "$2" : "$3"}
-                icon={isAddingComment ? <Spinner size="small" /> : <PaperPlaneTiltIcon size={14} />}
-                onPress={handleAddComment}
-                disabled={!commentText.trim() || isAddingComment}
-              >
-                {isAddingComment ? sendingLabel : commentLabel}
-              </Button>
-            </XStack>
+            {thread.replies.map((reply) => (
+              <React.Fragment key={reply.id}>{renderEntryNode(reply, rootId, true)}</React.Fragment>
+            ))}
+            {replyTarget &&
+              replyTarget.rootId === rootId &&
+              renderReplyComposer(
+                entries.find((e) => e.id === replyTarget.parentId) ?? thread.entry,
+              )}
           </YStack>
-        </XStack>
+        )}
       </YStack>
     );
   };
 
+  // Twin geometry for the loading rows: live avatar column width by size knob.
+  const skeletonAvatarPx = compact ? 20 : sz === "$5" ? 34 : 24;
+
   return (
     <YStack {...knobProps.gap} {...stackProps}>
       {label && (
         <XStack alignItems="center" justifyContent="space-between">
-          <H4 fontSize={compact ? "$4" : "$5"} fontWeight="600">
+          {/* Semantic tag follows headingLevel (default h2); the explicit
+              size spreads pin the visual scale at every level. */}
+          <LabelTag {...(compact ? { fontSize: "$4", fontWeight: "600" } : sectionHeading)}>
             {label}
-          </H4>
-          {entries.length > 0 && (
+          </LabelTag>
+          {/* Entry count hides on error so the badge can't lie (DG-ST-04).
+              Bidi-isolated so RTL contexts keep "7 entries" in one run. */}
+          {entries.length > 0 && !hasError && (
             <Text fontSize="$2" color={componentColors.text.muted}>
-              {entries.length} {entries.length === 1 ? entryLabel : entriesLabel}
+              {bidiIsolate(`${entries.length} ${entries.length === 1 ? entryLabel : entriesLabel}`)}
             </Text>
           )}
         </XStack>
       )}
 
-      {renderCommentInput()}
-
-      {enableAddComment && !disabled && onCommentAdded && entries.length > 0 && (
-        <Separator marginVertical="$2" />
-      )}
-
-      {entries.length === 0 ? (
-        emptyState
-      ) : (
-        <YStack gap="$1">
-          {entries.map((entry) => (
-            <React.Fragment key={entry.id}>{renderTimelineEntry(entry)}</React.Fragment>
-          ))}
+      {/* Composer hides on error: commenting into a feed that failed to load
+          would silently drop context (DG-ST-04 chrome semantics) */}
+      {!hasError && renderComposer()}
+
+      {/* Exactly one of: error → loading skeleton → empty → feed (W9 / DG-ST-01) */}
+      <AsyncBoundary
+        compact
+        error={error}
+        onRetry={onRetry}
+        errorTitle={loadFailedLabel}
+        loading={
+          showSkeleton ? (
+            <TimelineSkeleton
+              compact={compact}
+              avatarPx={skeletonAvatarPx}
+              loadingLabel={t("Loading")}
+            />
+          ) : (
+            false
+          )
+        }
+        empty={!hasError && entries.length === 0 ? emptyState : false}
+      >
+        <YStack
+          role="feed"
+          aria-label={label ?? t("Activity feed")}
+          gap={compact ? "$3" : knobProps.gapLg.gap}
+          marginTop={canCompose ? "$2" : undefined}
+        >
+          {threads.map((thread) => renderThread(thread))}
         </YStack>
-      )}
+      </AsyncBoundary>
     </YStack>
   );
 }