@stigmer/react 3.1.3 → 3.1.5

package/src/execution/ArtifactsWidget.tsx

@@ -5,9 +5,10 @@ import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexe
 import { cn } from "@stigmer/theme";
 import {
   useSessionArtifacts,
+  artifactKey,
   type SessionArtifactEntry,
 } from "../session/useSessionArtifacts.js";
-import { ArtifactCard } from "./ArtifactCard.js";
+import { ArtifactRow } from "./ArtifactRow.js";
 import { ArtifactPreviewModal } from "./ArtifactPreviewModal.js";
 import type { ApplyResourceResult } from "../library/useApplyResource.js";
 
@@ -45,19 +46,16 @@ export interface ArtifactsWidgetProps {
  * a file-explorer-like view of the conversation's output — no
  * execution/turn concepts are exposed.
  *
- * Composes {@link ArtifactCard} (summary + detection badges) with
- * {@link ArtifactPreviewModal} (full content review + Apply/Push CTA).
- * The card's "Preview" action opens the modal; the modal is the sole
- * location for Apply/Push actions (review-before-apply pattern).
+ * The panel-less counterpart of the session panel's Artifacts facet: it
+ * renders the same dense {@link ArtifactRow} list, but — having no editor pane
+ * to open document tabs into — a click opens the {@link ArtifactPreviewModal}
+ * (the review-before-apply popup, and the sole home of the Apply/Push CTA).
+ * This is the embeddable path a platform builder drops into their own sidebar.
  *
  * Returns `null` when the executions list is empty or no execution
  * has artifacts, matching the conditional-render pattern of
  * {@link ExecutionProgress} and {@link UsageWidget}.
  *
- * Renders without card chrome — each {@link ArtifactCard} provides its
- * own border and padding. The consumer controls the container styling
- * (or places the widget directly in a flex/grid layout).
- *
  * All visual properties flow through `--stgm-*` tokens.
  *
  * @example
@@ -74,7 +72,7 @@ export interface ArtifactsWidgetProps {
  * />
  * ```
  *
- * @see {@link ArtifactCard} — compact summary card per artifact
+ * @see {@link ArtifactRow} — the dense row rendered per artifact
  * @see {@link ArtifactPreviewModal} — full preview with Apply/Push CTA
  * @see {@link useSessionArtifacts} — headless session-level artifact aggregation hook
  * @see {@link useExecutionArtifacts} — headless single-execution artifact extraction hook
@@ -88,27 +86,22 @@ export function ArtifactsWidget({
   const { artifacts, hasArtifacts, artifactCount } =
     useSessionArtifacts(executions);
 
-  // Store the dedup key (sandboxPath or name) instead of a snapshot of
-  // the full entry.  The actual entry is derived from the live artifacts
-  // list on every render, so the preview modal always reflects the
-  // latest artifact version — even when a newer execution publishes an
-  // updated artifact for the same path while the modal is open.
+  // Store the artifact identity (not a snapshot of the full entry). The entry is
+  // re-derived from the live artifacts list on every render, so the modal always
+  // reflects the latest artifact version — even when a newer execution publishes
+  // an updated artifact for the same path while the modal is open.
   const [previewKey, setPreviewKey] = useState<string | null>(null);
 
   const previewEntry = useMemo<SessionArtifactEntry | null>(
     () =>
       previewKey !== null
-        ? artifacts.find(
-            (e) =>
-              (e.artifact.sandboxPath || e.artifact.name) === previewKey,
-          ) ?? null
+        ? artifacts.find((e) => artifactKey(e.artifact) === previewKey) ?? null
         : null,
     [previewKey, artifacts],
   );
 
-  const handlePreview = useCallback(
-    (entry: SessionArtifactEntry) =>
-      setPreviewKey(entry.artifact.sandboxPath || entry.artifact.name),
+  const handleOpen = useCallback(
+    (entry: SessionArtifactEntry) => setPreviewKey(artifactKey(entry.artifact)),
     [],
   );
 
@@ -123,19 +116,17 @@ export function ArtifactsWidget({
         </span>
       </div>
 
-      <div role="list" className="space-y-2">
+      <ul role="list" className="flex flex-col">
         {artifacts.map((entry) => (
-          <div key={entry.artifact.storageKey} role="listitem">
-            <ArtifactCard
-              artifact={entry.artifact}
-              executionId={entry.executionId}
-              org={org}
-              hasNameCollision={entry.hasNameCollision}
-              onPreview={() => handlePreview(entry)}
-            />
-          </div>
+          <ArtifactRow
+            key={artifactKey(entry.artifact)}
+            artifact={entry.artifact}
+            executionId={entry.executionId}
+            hasNameCollision={entry.hasNameCollision}
+            onOpen={() => handleOpen(entry)}
+          />
         ))}
-      </div>
+      </ul>
 
       {previewEntry && (
         <ArtifactPreviewModal

package/src/execution/FileReviewContext.ts

@@ -1,6 +1,10 @@
 import { createContext, useContext } from "react";
-import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type {
+  CapturedFileChange,
+  FileChangeSet,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import {
+  fileReviewRowChange,
   fileReviewRowState,
   type FileReviewRowState,
 } from "./file-review-status.js";
@@ -51,3 +55,25 @@ export function useFileReviewRowState(
   if (!fileChangeSetId) return null;
   return fileReviewRowState(changeSetsById.get(fileChangeSetId), rowPath);
 }
+
+/**
+ * The captured change a stamped tool row should render as its inline diff, or
+ * `null` to keep the row's own content view (unstamped row, unknown set, path
+ * miss, or a non-reviewable change — see {@link fileReviewRowChange} for the
+ * honest-degradation rules).
+ *
+ * The diff sibling of {@link useFileReviewRowState}: both read the same
+ * context entry through the same path matcher, so a row's badge and its diff
+ * always describe the same captured artifact.
+ *
+ * @param fileChangeSetId The row's `ToolCall.file_change_set_id` (may be "").
+ * @param rowPath The row's file path (the presenter's primary arg).
+ */
+export function useFileReviewRowChange(
+  fileChangeSetId: string,
+  rowPath: string | null,
+): CapturedFileChange | null {
+  const { changeSetsById } = useContext(FileReviewContext);
+  if (!fileChangeSetId) return null;
+  return fileReviewRowChange(changeSetsById.get(fileChangeSetId), rowPath);
+}

package/src/execution/MessageThread.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { lazy, memo, Suspense, useCallback, useMemo, useState } from "react";
+import { lazy, memo, Suspense, useCallback, useMemo, useState, type ComponentType } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
@@ -21,18 +21,19 @@ import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/
 import { displayFileChangeSets } from "@stigmer/sdk";
 import { cn } from "@stigmer/theme";
 import { isTerminalPhase } from "./execution-phases.js";
-import { MessageEntry } from "./MessageEntry.js";
+import { MessageEntry, type MessageEntryProps } from "./MessageEntry.js";
 import { ToolCallGroup } from "./ToolCallGroup.js";
 import { SubAgentSection } from "./SubAgentSection.js";
 import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge.js";
-import { SetupProgress } from "./SetupProgress.js";
-import { ApprovalCard } from "./ApprovalCard.js";
+import { SetupProgress, type SetupProgressProps } from "./SetupProgress.js";
+import { ApprovalCard, type ApprovalCardProps } from "./ApprovalCard.js";
 import { FileReviewCard } from "./FileReviewCard.js";
 import { SummarizationCard } from "./SummarizationCard.js";
-import { PlanCompletionCard } from "./PlanCompletionCard.js";
-import { PlanArtifactCard } from "./PlanArtifactCard.js";
-import { PlanStreamingCard } from "./PlanStreamingCard.js";
-import { TodoCard } from "./TodoCard.js";
+import { PlanCompletionCard, type PlanCompletionCardProps } from "./PlanCompletionCard.js";
+import { PlanArtifactCard, type PlanArtifactCardProps } from "./PlanArtifactCard.js";
+import { PlanStreamingCard, type PlanStreamingCardProps } from "./PlanStreamingCard.js";
+import { TodoCard, type TodoCardProps } from "./TodoCard.js";
+import type { TodoRowProps } from "./TodoList.js";
 import { findPlanArtifact } from "../library/detect-plan-artifact.js";
 import { findStreamingPlan } from "../library/detect-streaming-plan.js";
 import type { SummarizationEventView } from "./useContextWindow.js";
@@ -63,6 +64,49 @@ const EMPTY_APPROVALS: readonly PendingApproval[] = [];
 const EMPTY_SUBMITTING_IDS: ReadonlySet<string> = new Set();
 const EMPTY_APPROVAL_ERRORS: ReadonlyMap<string, Error> = new Map();
 
+/**
+ * Component overrides for the chrome {@link MessageThread} renders — the
+ * adaptation surface for hosts whose design system needs different
+ * *structure*, not just different `--stgm-*` token values (stigmer#187).
+ *
+ * Each slot is keyed by the built-in component it replaces and receives
+ * exactly that component's exported props interface, so an override can
+ * always delegate to the built-in for the cases it does not customize
+ * (e.g. a `MessageEntry` slot that restyles `MESSAGE_HUMAN` bubbles and
+ * renders the default `MessageEntry` for everything else).
+ *
+ * Define slot components at module level (or memoize them). The thread's
+ * rows rely on `React.memo` + structural sharing to skip re-renders during
+ * streaming (DD-009/DD-010); a slot component recreated on every host
+ * render defeats that for its rows.
+ */
+export interface MessageThreadSlots {
+  /**
+   * All message bubbles — human, assistant, thinking, and system entries.
+   * Also wraps the failed-send bubble (the inline Retry chrome around it
+   * stays built-in).
+   */
+  readonly MessageEntry?: ComponentType<MessageEntryProps>;
+  /** The HITL tool-approval gate card. */
+  readonly ApprovalCard?: ComponentType<ApprovalCardProps>;
+  /** The collapsible in-thread to-dos card. */
+  readonly TodoCard?: ComponentType<TodoCardProps>;
+  /**
+   * One to-do row inside the built-in {@link TodoCard}'s list. Ignored
+   * when `TodoCard` is also overridden (the replacement receives it via
+   * {@link TodoCardProps.TodoRow} and may forward or ignore it).
+   */
+  readonly TodoRow?: ComponentType<TodoRowProps>;
+  /** Completed Plan turn that published a plan artifact. */
+  readonly PlanArtifactCard?: ComponentType<PlanArtifactCardProps>;
+  /** Completed Plan turn without an artifact — the bare Implement CTA. */
+  readonly PlanCompletionCard?: ComponentType<PlanCompletionCardProps>;
+  /** Live stand-in card while a Plan turn is writing its document. */
+  readonly PlanStreamingCard?: ComponentType<PlanStreamingCardProps>;
+  /** Pre-first-token setup / "Thinking…" indicator. */
+  readonly SetupProgress?: ComponentType<SetupProgressProps>;
+}
+
 /** Props for {@link MessageThread}. */
 export interface MessageThreadProps {
   /** Completed executions in chronological order. */
@@ -261,6 +305,12 @@ export interface MessageThreadProps {
    * existing consumers see no layout change.
    */
   readonly contentColumn?: ThreadContentColumn;
+  /**
+   * Component overrides for the thread's chrome — see
+   * {@link MessageThreadSlots}. Omitted slots render the built-ins;
+   * omitting the prop entirely changes nothing (DD-011).
+   */
+  readonly slots?: MessageThreadSlots;
 }
 
 /** Reading-column alignment for {@link MessageThread} content. */
@@ -1020,6 +1070,7 @@ export function MessageThread({
   planActionsDisabled,
   planBuildPending,
   contentColumn,
+  slots,
 }: MessageThreadProps) {
   useRenderTracer("MessageThread", { executions, activeStreamExecution });
 
@@ -1124,6 +1175,7 @@ export function MessageThread({
             onRetrySend={onRetrySend}
             onRetryExecution={onRetryExecution}
             onEditMessage={onEditMessage}
+            slots={slots}
           />
         </Suspense>
       </div>
@@ -1152,6 +1204,7 @@ export function MessageThread({
       onRetrySend={onRetrySend}
       onRetryExecution={onRetryExecution}
       onEditMessage={onEditMessage}
+      slots={slots}
     />
   );
 }
@@ -1186,6 +1239,7 @@ interface NonVirtualizedThreadProps {
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
+  readonly slots?: MessageThreadSlots;
 }
 
 function NonVirtualizedThread({
@@ -1209,6 +1263,7 @@ function NonVirtualizedThread({
   onRetrySend,
   onRetryExecution,
   onEditMessage,
+  slots,
 }: NonVirtualizedThreadProps) {
   const { scrollRef, sentinelRef, contentRef, isFollowing, jumpToLatest } =
     useAutoScroll();
@@ -1252,6 +1307,7 @@ function NonVirtualizedThread({
                   onRetrySend={onRetrySend}
                   onRetryExecution={onRetryExecution}
                   onEditMessage={onEditMessage}
+                  slots={slots}
                 />
               </ThreadItemWrapper>
             ))}
@@ -1307,6 +1363,7 @@ export interface ThreadItemRendererProps {
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
+  readonly slots?: MessageThreadSlots;
 }
 
 /**
@@ -1314,6 +1371,11 @@ export interface ThreadItemRendererProps {
  * the non-virtualized `items.map()` path and the virtualized
  * `Virtuoso.itemContent` callback.
  *
+ * Slot resolution happens here, per case, as `slots?.X ?? X` — no merged
+ * defaults object, no allocation, and the memoized row wrappers below
+ * (`ApprovalCardRow`, `FileReviewRecordRow`) keep their DD-010 callback
+ * stabilization around whichever component renders inside them.
+ *
  * Does not receive a `key` prop — the caller is responsible for
  * keying (either via `items.map` or `computeItemKey`).
  *
@@ -1334,16 +1396,22 @@ export function ThreadItemRenderer({
   onRetrySend,
   onRetryExecution,
   onEditMessage,
+  slots,
 }: ThreadItemRendererProps) {
   switch (item.kind) {
-    case "message":
+    case "message": {
+      const Entry = slots?.MessageEntry ?? MessageEntry;
       if (item.isFailed) {
         return (
-          <FailedUserMessage message={item.message} onRetry={onRetrySend} />
+          <FailedUserMessage
+            message={item.message}
+            onRetry={onRetrySend}
+            MessageEntryComponent={Entry}
+          />
         );
       }
       return (
-        <MessageEntry
+        <Entry
           message={item.message}
           className={item.isPending ? "opacity-70" : undefined}
           isPlanDocument={item.isPlanDocument}
@@ -1355,6 +1423,7 @@ export function ThreadItemRenderer({
           }
         />
       );
+    }
     case "tool-group":
       return (
         <ToolCallGroup
@@ -1392,30 +1461,37 @@ export function ThreadItemRenderer({
           onApprovalSubmit={onApprovalSubmit!}
           isSubmitting={submittingApprovalIds?.has(item.pendingApproval.toolCallId) ?? false}
           error={approvalErrors?.get(item.pendingApproval.toolCallId) ?? null}
+          ApprovalCardComponent={slots?.ApprovalCard ?? ApprovalCard}
         />
       );
     case "file-review-record":
       return <FileReviewRecordRow fileChangeSet={item.fileChangeSet} />;
-    case "setup-progress":
+    case "setup-progress": {
+      const Setup = slots?.SetupProgress ?? SetupProgress;
       return (
-        <SetupProgress
+        <Setup
           workspaceEntries={item.workspaceEntries}
           serverPhase={item.serverPhase}
           isAwaitingResponse={item.isAwaitingResponse}
         />
       );
+    }
     case "context-compacted":
       return <SummarizationCard event={item.event} />;
-    case "todos":
-      return <TodoCard todos={item.todos} className="mx-4" />;
-    case "plan-completion":
+    case "todos": {
+      const Todos = slots?.TodoCard ?? TodoCard;
+      return <Todos todos={item.todos} className="mx-4" TodoRow={slots?.TodoRow} />;
+    }
+    case "plan-completion": {
       // When the plan was published as an artifact, show the richer reviewable
       // card (preview / copy / download / implement). Otherwise fall back to the
       // bare Implement CTA (older executions, or a plan that failed to publish).
       // Only the latest plan receives the build action — a superseded plan's
       // card is review-only, so a stale plan can never be implemented from it.
+      const Artifact = slots?.PlanArtifactCard ?? PlanArtifactCard;
+      const Completion = slots?.PlanCompletionCard ?? PlanCompletionCard;
       return item.planArtifact && item.executionId ? (
-        <PlanArtifactCard
+        <Artifact
           executionId={item.executionId}
           artifact={item.planArtifact}
           title={item.planTitle}
@@ -1432,17 +1508,19 @@ export function ThreadItemRenderer({
           buildPending={planBuildPending}
         />
       ) : (
-        <PlanCompletionCard
+        <Completion
           onImplement={item.isLatestPlan ? onBuildFromPlan : undefined}
           disabled={planActionsDisabled}
         />
       );
-    case "plan-writing":
+    }
+    case "plan-writing": {
       // The live stand-in for a plan the active turn is writing. Emitted only
       // when onOpenPlan is wired (see buildThreadItems' collapseStreamingPlan
       // gate), so the action is always available in practice.
+      const Streaming = slots?.PlanStreamingCard ?? PlanStreamingCard;
       return (
-        <PlanStreamingCard
+        <Streaming
           title={item.planTitle}
           sizeBytes={item.planSize}
           onOpenPlan={
@@ -1450,6 +1528,7 @@ export function ThreadItemRenderer({
           }
         />
       );
+    }
   }
 }
 
@@ -1462,17 +1541,22 @@ export function ThreadItemRenderer({
  * (so the typed text is never lost) with an inline, actionable error beneath
  * it. The error copy is intentionally short — the full reason is surfaced by
  * the consumer's send-error banner; this is the in-thread "Retry" affordance.
+ *
+ * The bubble renders through the caller-resolved MessageEntry slot so an
+ * overridden bubble style also applies to failed sends.
  */
 function FailedUserMessage({
   message,
   onRetry,
+  MessageEntryComponent,
 }: {
   message: AgentMessage;
   onRetry?: () => void;
+  MessageEntryComponent: ComponentType<MessageEntryProps>;
 }) {
   return (
     <div className="flex flex-col gap-1">
-      <MessageEntry message={message} />
+      <MessageEntryComponent message={message} />
       <div
         role="alert"
         className="mx-4 flex items-center gap-2 text-xs text-destructive"
@@ -1587,6 +1671,9 @@ interface ApprovalCardRowProps {
   // This gate's last failed decision, or null — a stable ref from the
   // approvalErrors map, so the row re-renders only when its error appears/clears.
   readonly error?: Error | null;
+  // The (possibly slotted) card component. The row's callback stabilization
+  // wraps whichever card renders, so a slot override keeps the memo behavior.
+  readonly ApprovalCardComponent: ComponentType<ApprovalCardProps>;
 }
 
 const ApprovalCardRow = memo(function ApprovalCardRow({
@@ -1594,6 +1681,7 @@ const ApprovalCardRow = memo(function ApprovalCardRow({
   onApprovalSubmit,
   isSubmitting,
   error = null,
+  ApprovalCardComponent,
 }: ApprovalCardRowProps) {
   const handleSubmit = useCallback(
     (action: ApprovalAction, comment?: string) => {
@@ -1603,7 +1691,7 @@ const ApprovalCardRow = memo(function ApprovalCardRow({
   );
 
   return (
-    <ApprovalCard
+    <ApprovalCardComponent
       pendingApproval={pendingApproval}
       onSubmit={handleSubmit}
       isSubmitting={isSubmitting}

package/src/execution/TodoCard.tsx

@@ -1,12 +1,17 @@
 "use client";
 
-import { memo, useMemo } from "react";
+import { memo, useMemo, type ComponentType } from "react";
 import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
 import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 import { useRenderTracer } from "../internal/dev/index.js";
 import { useAutoDisclosure } from "../internal/useAutoDisclosure.js";
-import { TodoList, findActiveTodo, todoCompletionSummary } from "./TodoList.js";
+import {
+  TodoList,
+  findActiveTodo,
+  todoCompletionSummary,
+  type TodoRowProps,
+} from "./TodoList.js";
 
 /** Props for {@link TodoCard}. */
 export interface TodoCardProps {
@@ -18,6 +23,12 @@ export interface TodoCardProps {
   readonly todos: { readonly [key: string]: TodoItem };
   /** Additional CSS class names for the root container. */
   readonly className?: string;
+  /**
+   * Replacement row component, forwarded to the inner {@link TodoList}.
+   * Lets a host restyle individual rows while keeping the card's
+   * collapse/progress chrome. Defaults to the built-in {@link TodoRow}.
+   */
+  readonly TodoRow?: ComponentType<TodoRowProps>;
 }
 
 /**
@@ -52,6 +63,7 @@ export interface TodoCardProps {
 export const TodoCard = memo(function TodoCard({
   todos,
   className,
+  TodoRow,
 }: TodoCardProps) {
   useRenderTracer("TodoCard", { todos });
 
@@ -121,7 +133,7 @@ export const TodoCard = memo(function TodoCard({
 
       {expanded && (
         <div className="border-t border-border-muted px-2.5 py-2">
-          <TodoList todos={todos} />
+          <TodoList todos={todos} TodoRow={TodoRow} />
         </div>
       )}
     </div>
@@ -139,7 +151,11 @@ export function todoCardPropsEqual(
   prev: Readonly<TodoCardProps>,
   next: Readonly<TodoCardProps>,
 ): boolean {
-  return prev.todos === next.todos && prev.className === next.className;
+  return (
+    prev.todos === next.todos &&
+    prev.className === next.className &&
+    prev.TodoRow === next.TodoRow
+  );
 }
 
 // ---------------------------------------------------------------------------

package/src/execution/TodoList.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo } from "react";
+import { useMemo, type ComponentType } from "react";
 import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
 import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
@@ -14,6 +14,12 @@ export interface TodoListProps {
   readonly todos: { readonly [key: string]: TodoItem };
   /** Additional CSS class names for the root container. */
   readonly className?: string;
+  /**
+   * Replacement row component. Receives {@link TodoRowProps} for each
+   * item; defaults to the built-in {@link TodoRow}. Renders inside a
+   * `<ul role="list">`, so the component must produce an `<li>`.
+   */
+  readonly TodoRow?: ComponentType<TodoRowProps>;
 }
 
 const STATUS_SORT_ORDER: ReadonlyMap<TodoStatus, number> = new Map([
@@ -47,7 +53,11 @@ function todoSortKey(item: TodoItem): number {
  * <TodoList todos={todos} />
  * ```
  */
-export function TodoList({ todos, className }: TodoListProps) {
+export function TodoList({
+  todos,
+  className,
+  TodoRow: RowComponent = TodoRow,
+}: TodoListProps) {
   const sortedTodos = useMemo(() => {
     const items = Object.values(todos);
     if (items.length === 0) return [];
@@ -63,7 +73,7 @@ export function TodoList({ todos, className }: TodoListProps) {
       aria-label="Tasks"
     >
       {sortedTodos.map((item) => (
-        <TodoRow key={item.id} item={item} />
+        <RowComponent key={item.id} item={item} />
       ))}
     </ul>
   );
@@ -108,7 +118,19 @@ export function todoCompletionSummary(
 // TodoRow — single todo item with status icon
 // ---------------------------------------------------------------------------
 
-function TodoRow({ item }: { readonly item: TodoItem }) {
+/** Props for {@link TodoRow}. */
+export interface TodoRowProps {
+  /** The todo item to render. */
+  readonly item: TodoItem;
+}
+
+/**
+ * One to-do checklist row: status icon plus task description, rendered as
+ * an `<li>`. The default row for {@link TodoList} — replace it via the
+ * `TodoRow` prop (or `MessageThread`'s `slots.TodoRow`) to restyle rows or
+ * bring host iconography while keeping the built-in card chrome.
+ */
+export function TodoRow({ item }: TodoRowProps) {
   const Icon = TODO_ICONS[item.status] ?? TodoPendingIcon;
   const colorClass = TODO_COLORS[item.status] ?? "text-muted-foreground";
   const cancelled = item.status === TodoStatus.TODO_CANCELLED;